forjajs 5.0.1 → 5.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 (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -48,6 +48,15 @@ CREATE VIRTUAL TABLE IF NOT EXISTS search_idx USING fts5(
48
48
  content,
49
49
  tokenize='porter'
50
50
  );
51
+
52
+ -- Uma linha por execução de sync. Existe porque um sync incremental que pula tudo não escreve byte
53
+ -- nenhum no banco, e o doctor compara o mtime do banco com o de memory/ (check memory-fresh): sem
54
+ -- ela, o índice em dia pareceria velho. De quebra carrega os contadores da execução.
55
+ CREATE TABLE IF NOT EXISTS sync_meta (
56
+ name TEXT PRIMARY KEY,
57
+ value TEXT NOT NULL,
58
+ updated_at TEXT NOT NULL
59
+ );
51
60
  `;
52
61
  function log(msg, level = 'info') {
53
62
  const prefix = { info: 'INFO', success: 'OK', warn: 'WARN', error: 'ERROR' }[level] || 'INFO';
@@ -95,6 +104,8 @@ const upsertProject = db.prepare('INSERT INTO projects (name, path, created_at)
95
104
  // um documento sob o node_id de outro (ADR-0021).
96
105
  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 project_id=excluded.project_id, kind=excluded.kind, title=excluded.title, content=excluded.content, content_hash=excluded.content_hash, updated_at=excluded.updated_at RETURNING id');
97
106
  const getProjectId = db.prepare('SELECT id FROM projects WHERE name = ?');
107
+ const getStoredNode = db.prepare('SELECT content_hash, project_id FROM memory_nodes WHERE path = ?');
108
+ const upsertSyncMeta = db.prepare('INSERT INTO sync_meta (name, value, updated_at) VALUES (?, ?, ?) ON CONFLICT(name) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at');
98
109
  const deleteFts = db.prepare('DELETE FROM search_idx WHERE node_id = ?');
99
110
  const insertFts = db.prepare('INSERT INTO search_idx (node_id, title, content) VALUES (?, ?, ?)');
100
111
  const purgeFtsOrphans = db.prepare('DELETE FROM search_idx WHERE node_id NOT IN (SELECT id FROM memory_nodes)');
@@ -230,22 +241,70 @@ function syncAssetCatalog() {
230
241
  }
231
242
  log(`Asset catalog sincronizado: ${assets.length}`, 'info');
232
243
  }
244
+ /** Contadores da execução: o log diz quanto do sync foi trabalho de verdade e quanto foi pulado. */
245
+ const tally = { indexados: 0, pulados: 0, falhas: 0 };
246
+ /**
247
+ * `abs` está mesmo dentro de `base`? `startsWith('..')` não basta: em Windows, `path.relative()` entre
248
+ * unidades diferentes devolve o caminho **absoluto** de `abs` — que não começa por `..` e seria lido
249
+ * como "está dentro".
250
+ */
251
+ function inside(base, abs) {
252
+ const rel = path.relative(base, abs);
253
+ return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
254
+ }
255
+ const realCache = new Map();
256
+ function realOf(p) {
257
+ let v = realCache.get(p);
258
+ if (v === undefined) {
259
+ try {
260
+ v = fs.realpathSync(p);
261
+ }
262
+ catch {
263
+ v = p;
264
+ }
265
+ realCache.set(p, v);
266
+ }
267
+ return v;
268
+ }
269
+ /**
270
+ * Caminho do nó: relativo à raiz cujo conteúdo ele é, na mesma forma em qualquer máquina. Dois
271
+ * atalhos unix-cêntricos gravavam o mesmo arquivo com duas identidades no Windows — `relative()`
272
+ * entre unidade diferente devolve caminho absoluto, e `os.tmpdir()` chega como nome 8.3
273
+ * (`RUNNER~1`) enquanto o walk devolve a forma longa, o que faz o `relative()` subir a árvore toda e
274
+ * cair na raiz errada. Se a forma direta não contém o arquivo, tenta a canônica dos dois lados.
275
+ */
276
+ function nodePathOf(abs) {
277
+ for (const base of [contentRoot, operationRoot]) {
278
+ if (inside(base, abs))
279
+ return path.relative(base, abs);
280
+ if (inside(realOf(base), realOf(abs)))
281
+ return path.relative(realOf(base), realOf(abs));
282
+ }
283
+ return path.relative(contentRoot, abs);
284
+ }
233
285
  function syncFiles(files, projectId = null) {
234
286
  for (const abs of files) {
235
- let rel = path.relative(contentRoot, abs);
236
- if (rel.startsWith('..')) {
237
- rel = path.relative(operationRoot, abs);
238
- }
287
+ const rel = nodePathOf(abs);
239
288
  const raw = fs.readFileSync(abs, 'utf8');
240
289
  const hash = crypto.createHash('sha256').update(raw).digest('hex');
290
+ // O `content_hash` sempre foi gravado e nunca foi comparado: todo sync re-upsertava e re-indexava
291
+ // os 289 nós do pacote. Pular o inalterado é seguro — a linha e o trecho FTS continuam lá — e o
292
+ // project_id entra na comparação porque o mesmo path pode mudar de dono (global ↔ projeto).
293
+ const stored = getStoredNode.get(rel);
294
+ if (stored && stored.content_hash === hash && stored.project_id === projectId) {
295
+ tally.pulados++;
296
+ continue;
297
+ }
241
298
  const titleMatch = raw.match(/^#\s+(.+)$/m);
242
299
  const title = titleMatch ? titleMatch[1].trim() : path.basename(rel, '.md');
243
300
  try {
244
301
  const { id: nodeId } = upsertNode.get(projectId, rel, getKind(rel), title, raw, hash, now);
245
302
  deleteFts.run(nodeId);
246
303
  insertFts.run(nodeId, title, raw);
304
+ tally.indexados++;
247
305
  }
248
306
  catch (e) {
307
+ tally.falhas++;
249
308
  log(`Erro sincronizando ${rel}: ${e.message}`, 'error');
250
309
  }
251
310
  }
@@ -309,5 +368,11 @@ if (mode === 'studio' && fs.existsSync(workspaceProjectsMemoryDir)) {
309
368
  const orphans = purgeFtsOrphans.run().changes;
310
369
  if (orphans)
311
370
  log(`Índice FTS: ${orphans} linhas órfãs removidas`, 'info');
371
+ // Marca a execução mesmo quando tudo foi pulado — ver o comentário de `sync_meta` no schema.
372
+ upsertSyncMeta.run('last_sync', JSON.stringify({ at: now, ...tally }), now);
373
+ log(`Nós: ${tally.indexados} indexados · ${tally.pulados} inalterados (pulados) · ${tally.falhas} falhas`, 'info');
374
+ // O banco abre em WAL: sem checkpoint, uma escrita pequena fica no -wal e o mtime do .db não muda —
375
+ // o arquivo principal passa a mentir sobre a idade do índice (e vale menos sozinho, sem o -wal).
376
+ db.pragma('wal_checkpoint(TRUNCATE)');
312
377
  db.close();
313
378
  log('Sincronização Universal Concluída!', 'success');
@@ -13,8 +13,40 @@
13
13
  * Estimar tokens (1KB ≈ 250 tokens, aproximação)
14
14
  */
15
15
  declare function estimateTokens(content: any): number;
16
+ /**
17
+ * Formatar bytes em legível
18
+ */
19
+ declare function formatBytes(bytes: any): string;
20
+ declare function walkMarkdown(dir: any, out?: string[]): string[];
21
+ /**
22
+ * O projeto de referência sai do banco, não de um nome chutado. O benchmark media
23
+ * 'benchmark-project', que não existe em lugar nenhum: domain e task voltavam só com os nós globais e
24
+ * o relatório anunciava ~99% de "economia" por não ter injetado quase nada (achado da SPEC-057 —
25
+ * medição que não mede é pior que medição nenhuma, porque decide no escuro com ar de número).
26
+ */
27
+ declare function referenceProject(dbPath: string): {
28
+ name: string;
29
+ nodes: number;
30
+ } | null;
31
+ /** Nós injetados no pacote. Comparado com o do modo global, diz se o projeto contribuiu com algo. */
32
+ declare function nodesIn(pack: string): number;
33
+ /**
34
+ * Termo do modo task: um que existe no projeto (o primeiro domínio indexado, senão o primeiro slug de
35
+ * spec). O termo chutado em inglês que estava aqui antes — 'architecture implementation' — não casa
36
+ * com memória em pt-BR, e o modo task media um pacote sem nenhum nó do projeto.
37
+ */
38
+ declare function taskKeyword(dbPath: string, project: string): string;
39
+ interface RefRow {
40
+ keyword: string;
41
+ nodes: number;
42
+ trecho: number;
43
+ integral: number;
44
+ corte: number;
45
+ }
46
+ declare function referenceScenario(): RefRow[];
47
+ declare function referenceScenarioReport(rows: RefRow[] | null): void;
16
48
  /**
17
49
  * Executar benchmark
18
50
  */
19
51
  declare function benchmark(): Promise<void>;
20
- export { benchmark, estimateTokens };
52
+ export { benchmark, estimateTokens, formatBytes, walkMarkdown, nodesIn, referenceProject, referenceScenario, referenceScenarioReport, taskKeyword, };
@@ -10,11 +10,14 @@
10
10
  * Uso: npm run token:benchmark
11
11
  */
12
12
  import fs from 'node:fs';
13
+ import os from 'node:os';
13
14
  import path from 'node:path';
15
+ import { spawnSync } from 'node:child_process';
16
+ import Database from 'better-sqlite3';
14
17
  import ContextBuilder from '../lib/context-builder.js';
15
18
  import { fileURLToPath } from 'node:url';
16
19
  import { getDbPath, ensureSchema } from './memory-schema.js';
17
- import { pkgRoot } from '../lib/paths.js';
20
+ import { pkgRoot, script } from '../lib/paths.js';
18
21
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
19
22
  const root = pkgRoot;
20
23
  /**
@@ -49,6 +52,132 @@ function walkMarkdown(dir, out = []) {
49
52
  }
50
53
  return out;
51
54
  }
55
+ /**
56
+ * O projeto de referência sai do banco, não de um nome chutado. O benchmark media
57
+ * 'benchmark-project', que não existe em lugar nenhum: domain e task voltavam só com os nós globais e
58
+ * o relatório anunciava ~99% de "economia" por não ter injetado quase nada (achado da SPEC-057 —
59
+ * medição que não mede é pior que medição nenhuma, porque decide no escuro com ar de número).
60
+ */
61
+ function referenceProject(dbPath) {
62
+ const db = new Database(dbPath, { readonly: true });
63
+ try {
64
+ const row = db.prepare(`
65
+ SELECT p.name AS name, COUNT(n.id) AS nodes
66
+ FROM projects p JOIN memory_nodes n ON n.project_id = p.id
67
+ GROUP BY p.id ORDER BY nodes DESC LIMIT 1
68
+ `).get();
69
+ return row && row.nodes > 0 ? row : null;
70
+ }
71
+ finally {
72
+ db.close();
73
+ }
74
+ }
75
+ /** Nós injetados no pacote. Comparado com o do modo global, diz se o projeto contribuiu com algo. */
76
+ function nodesIn(pack) {
77
+ return (pack.match(/^## 📄 /gm) || []).length;
78
+ }
79
+ /**
80
+ * Termo do modo task: um que existe no projeto (o primeiro domínio indexado, senão o primeiro slug de
81
+ * spec). O termo chutado em inglês que estava aqui antes — 'architecture implementation' — não casa
82
+ * com memória em pt-BR, e o modo task media um pacote sem nenhum nó do projeto.
83
+ */
84
+ function taskKeyword(dbPath, project) {
85
+ const db = new Database(dbPath, { readonly: true });
86
+ try {
87
+ const rows = db.prepare(`
88
+ SELECT n.path AS path FROM memory_nodes n JOIN projects p ON p.id = n.project_id
89
+ WHERE p.name = ? ORDER BY n.path LIMIT 200
90
+ `).all(project);
91
+ for (const row of rows) {
92
+ const domain = /30-domains\/([^/]+)\//.exec(row.path)?.[1];
93
+ if (domain)
94
+ return domain;
95
+ }
96
+ const spec = rows.find((r) => r.path.includes('specs/'));
97
+ return spec ? path.basename(path.dirname(spec.path)) : 'regra';
98
+ }
99
+ finally {
100
+ db.close();
101
+ }
102
+ }
103
+ /**
104
+ * Cenário de referência da SPEC-057 (AC-2): um projeto descartável com 60 nós de ~2,5KB — o volume
105
+ * mínimo que o critério pede — gerado com texto fixo. Fixo porque número de economia que muda entre
106
+ * máquinas ou execuções não é evidência, é ruído.
107
+ *
108
+ * Os três termos cobrem os três caminhos do pack: FTS (casa e devolve `snippet()`), LIKE (substring
109
+ * no meio de palavra, que o porter não casa → janela calculada aqui) e nenhum (só globais).
110
+ */
111
+ const REF_PROJECT = 'ref-spec-057';
112
+ const REF_NODES = 60;
113
+ const REF_KEYWORDS = ['pagamentos', 'pagament', 'pagamentosavancado', 'termo-inexistente'];
114
+ function refNodeBody(i, termo) {
115
+ let body = `# Nota ${i} de ${termo}\n\n`;
116
+ for (let s = 0; s < 6; s++) {
117
+ body += `## Seção ${s}\n\n`;
118
+ body += `Este nó documenta a regra de ${termo} aplicada ao fluxo de pedidos: o agregado valida o ` +
119
+ `invariante, o repositório persiste e a apresentação traduz o resultado. O recálculo de ${termo} ` +
120
+ `usa duas casas decimais e publica evento com o identificador idempotente da tentativa anterior, ` +
121
+ `o que evita duplicidade no consumidor a jusante.\n\n`;
122
+ body += '- item de lista com contexto suficiente para ocupar uma linha inteira\n- outro item\n';
123
+ }
124
+ return body;
125
+ }
126
+ function referenceScenario() {
127
+ const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-ref-'));
128
+ try {
129
+ const proj = path.join(ws, 'projects', REF_PROJECT);
130
+ const write = (rel, body) => {
131
+ const abs = path.join(proj, rel);
132
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
133
+ fs.writeFileSync(abs, body);
134
+ };
135
+ for (let i = 0; i < REF_NODES; i++) {
136
+ write(path.join('memory', '30-domains', `dom${i % 6}`, `nota-${i}.md`), refNodeBody(i, i % 3 === 0 ? 'pagamentos' : 'cobranca'));
137
+ }
138
+ write(path.join('docs', 'guia-pagamentosavancado.md'), refNodeBody(900, 'pagamentosavancado'));
139
+ const sync = spawnSync(process.execPath, [script('bin/forja'), 'sync:universal'], {
140
+ cwd: root,
141
+ encoding: 'utf8',
142
+ env: { ...process.env, FORJA_WORKSPACE: ws },
143
+ });
144
+ if (sync.status !== 0)
145
+ throw new Error(`sync do cenário de referência falhou: ${sync.stderr || sync.stdout}`);
146
+ const builder = new ContextBuilder(proj, path.join(ws, 'memory', 'sqlite', 'universal.db'));
147
+ try {
148
+ return REF_KEYWORDS.map((keyword) => {
149
+ const trecho = builder.build('task', REF_PROJECT, keyword);
150
+ const integral = builder.build('task', REF_PROJECT, keyword, { full: true });
151
+ const a = estimateTokens(trecho.length);
152
+ const b = estimateTokens(integral.length);
153
+ return { keyword, nodes: nodesIn(trecho), trecho: a, integral: b, corte: b === 0 ? 0 : Math.round(((b - a) / b) * 100) };
154
+ });
155
+ }
156
+ finally {
157
+ builder.close();
158
+ }
159
+ }
160
+ finally {
161
+ fs.rmSync(ws, { recursive: true, force: true });
162
+ }
163
+ }
164
+ function referenceScenarioReport(rows) {
165
+ console.log(`Cenário de referência SPEC-057 — ${REF_NODES} nós gerados, trecho FTS5 vs conteúdo integral\n`);
166
+ if (!rows) {
167
+ console.warn(' não foi possível medir\n');
168
+ return;
169
+ }
170
+ for (const r of rows) {
171
+ console.log(` "${r.keyword}"`.padEnd(28) + `${String(r.nodes).padStart(3)} nós · trecho ${String(r.trecho).padStart(6)} vs integral ${String(r.integral).padStart(6)} tokens · −${r.corte}%`);
172
+ }
173
+ // O AC-2 olha o termo que casa: é para ele que o `snippet()` existe. O termo sem casamento entra na
174
+ // tabela como controle — ali o pacote é só o global, e a redução diz respeito à política de cabeça.
175
+ const fts = rows.find((r) => r.keyword === 'pagamentos');
176
+ if (fts)
177
+ console.log(`\n Meta AC-2 (≥ 50% no termo que casa): −${fts.corte}% → ${fts.corte >= 50 ? '✅' : '❌'}\n`);
178
+ else
179
+ console.log('');
180
+ }
52
181
  /**
53
182
  * Executar benchmark
54
183
  */
@@ -56,12 +185,29 @@ async function benchmark() {
56
185
  console.log('Token Economy Benchmark\n');
57
186
  ensureSchema({ silent: true });
58
187
  const dbPath = getDbPath();
59
- const project = 'benchmark-project';
60
188
  if (!fs.existsSync(dbPath)) {
61
189
  console.warn('Database not found at:', dbPath);
62
190
  console.log(' Run: npm run memory:db:init');
63
191
  process.exit(1);
64
192
  }
193
+ // O cenário de referência da SPEC-057 vem antes: não depende de projeto indexado e é o número
194
+ // reproduzível (mesma fixture, qualquer máquina) que a evidência do AC-2 cita.
195
+ let refRows = null;
196
+ try {
197
+ refRows = referenceScenario();
198
+ }
199
+ catch (e) {
200
+ console.warn(` medir o cenário de referência falhou: ${e.message}`);
201
+ }
202
+ referenceScenarioReport(refRows);
203
+ const ref = referenceProject(dbPath);
204
+ if (!ref) {
205
+ console.warn('Nenhum projeto indexado no banco — os modos domain/task do SEU projeto ficaram de fora.');
206
+ console.log(' Rode dentro de um projeto: forja sync:universal\n');
207
+ return;
208
+ }
209
+ const project = ref.name;
210
+ console.log(`Projeto indexado: ${project} (${ref.nodes} nós)\n`);
65
211
  const builder = new ContextBuilder(root, dbPath);
66
212
  try {
67
213
  // 1. Simular contexto "antigo" (sem smart context)
@@ -96,10 +242,13 @@ async function benchmark() {
96
242
  console.log(` Cost: $${baselineCost}\n`);
97
243
  // 2. Testar 3 modos de contexto inteligente
98
244
  const modes = ['global', 'domain', 'task'];
245
+ const keywordTask = taskKeyword(dbPath, project);
99
246
  const results = [];
247
+ let globalNodes = 0;
248
+ let excerptAxis = null;
100
249
  for (const mode of modes) {
101
250
  console.log(`Scenario: ${mode.toUpperCase()} Mode\n`);
102
- const keyword = mode === 'task' ? 'architecture implementation' : '';
251
+ const keyword = mode === 'task' ? keywordTask : '';
103
252
  const start = Date.now();
104
253
  let context = '';
105
254
  try {
@@ -115,11 +264,30 @@ async function benchmark() {
115
264
  const tokens = estimateTokens(size);
116
265
  const cost = (tokens * 0.00001).toFixed(5);
117
266
  const savings = (((baselineTokens - tokens) / baselineTokens) * 100).toFixed(1);
267
+ const nodes = nodesIn(context);
268
+ if (mode === 'global')
269
+ globalNodes = nodes;
118
270
  console.log(` Size: ${formatBytes(size)}`);
119
271
  console.log(` Tokens: ${tokens.toLocaleString()}`);
272
+ console.log(` Nodes: ${nodes}`);
120
273
  console.log(` Time: ${duration}ms`);
121
274
  console.log(` Cost: $${cost}`);
122
- console.log(` Savings: ${savings}% (vs baseline)\n`);
275
+ console.log(` Savings: ${savings}% (vs baseline)`);
276
+ // Sem isto o relatório anuncia economia por não ter injetado nada: se domain/task não trazem um
277
+ // nó a mais que global, o projeto não entrou no pacote e o número não mede o que diz medir.
278
+ if (mode !== 'global' && nodes <= globalNodes) {
279
+ console.log(` ⚠️ nenhum nó do projeto além dos globais — economia vazia, não conte este número`);
280
+ }
281
+ console.log('');
282
+ // Eixo SPEC-057: o mesmo pacote com o conteúdo integral de cada nó (--full-context) vs o trecho
283
+ // casado que o FTS devolve. É a redução que o corte de trecho compra, medida no projeto real.
284
+ if (mode === 'task') {
285
+ const integral = estimateTokens(builder.build(mode, project, keyword, { full: true }).length);
286
+ const corte = integral === 0 ? 0 : Math.round(((integral - tokens) / integral) * 100);
287
+ console.log(` Trecho vs integral (SPEC-057): ${tokens.toLocaleString()} vs ${integral.toLocaleString()} tokens → −${corte}%`);
288
+ console.log(` Meta AC-2: ≥ 50% → ${corte >= 50 ? '✅' : '❌'}\n`);
289
+ excerptAxis = { trecho: tokens, integral, corte };
290
+ }
123
291
  results.push({
124
292
  mode,
125
293
  size,
@@ -146,6 +314,12 @@ async function benchmark() {
146
314
  console.log(` Tokens: ${bestMode.tokens.toLocaleString()}`);
147
315
  console.log(` Cost: $${bestMode.cost.toFixed(5)}`);
148
316
  console.log(` Savings: ${bestMode.savings.toFixed(1)}%\n`);
317
+ if (excerptAxis) {
318
+ console.log(`Trecho vs integral (SPEC-057, modo task em ${project})`);
319
+ console.log(` Com snippet FTS5: ${excerptAxis.trecho.toLocaleString()} tokens`);
320
+ console.log(` Conteúdo integral: ${excerptAxis.integral.toLocaleString()} tokens`);
321
+ console.log(` Redução: −${excerptAxis.corte}% (meta AC-2: ≥ 50%)\n`);
322
+ }
149
323
  // 4. Cálculo de ROI
150
324
  const monthlyRequests = 1000;
151
325
  const savedCostPerMonth = (baselineTokens - avgTokens) * 0.00001 * monthlyRequests;
@@ -179,4 +353,4 @@ async function benchmark() {
179
353
  if (import.meta.url === `file://${process.argv[1]}`) {
180
354
  benchmark().catch(console.error);
181
355
  }
182
- export { benchmark, estimateTokens };
356
+ export { benchmark, estimateTokens, formatBytes, walkMarkdown, nodesIn, referenceProject, referenceScenario, referenceScenarioReport, taskKeyword, };
@@ -45,7 +45,9 @@ function projectMode(projectRoot) {
45
45
  say('Para cada domínio: ler o mapa (context.md) vs ler todo o código da fatia.\n');
46
46
  const rows = [];
47
47
  for (const domain of domains) {
48
- const pack = buildContextPack({ projectRoot, domain, includeCode: true });
48
+ // `full: true` de propósito: este eixo mede o custo de ler a fatia INTEIRA no frio. Com o
49
+ // orçamento da SPEC-057 ligado, mediríamos o pacote cortado e o −61% viraria ficção.
50
+ const pack = buildContextPack({ projectRoot, domain, includeCode: true, full: true });
49
51
  const economy = pack.codeTokens === 0 ? '—' : `−${Math.round(((pack.codeTokens - pack.mapTokens) / pack.codeTokens) * 100)}%`;
50
52
  rows.push({ domínio: domain, mapa_tok: pack.mapTokens, código_tok: pack.codeTokens, mapa_vs_código: economy });
51
53
  say(`■ ${domain}`);
@@ -17,4 +17,19 @@
17
17
  *
18
18
  * Uso: forja tools:doctor
19
19
  */
20
- export {};
20
+ export interface ToolState {
21
+ readonly name: string;
22
+ readonly role: string;
23
+ readonly gate: string;
24
+ readonly install: string;
25
+ readonly ok: boolean;
26
+ readonly version: string | null;
27
+ }
28
+ export interface ProjectWiring {
29
+ readonly status: 'ok' | 'warn' | 'fail';
30
+ readonly checks: readonly {
31
+ id: string;
32
+ status: string;
33
+ detail: string;
34
+ }[];
35
+ }
@@ -21,6 +21,7 @@ import { spawnSync } from 'node:child_process';
21
21
  import fs from 'node:fs';
22
22
  import path from 'node:path';
23
23
  import { runChecks, worstStatus, bucketFor, BUCKET_LABEL } from '../lib/core/health.js';
24
+ import { emitError, emitOk } from '../lib/cli-output.js';
24
25
  import { COMMANDS } from '../lib/core/registry.js';
25
26
  import { checkProjectWiring } from '../lib/project-wiring.js';
26
27
  import { isInsideFrameworkRepo } from '../lib/workspace.js';
@@ -64,10 +65,18 @@ const TOOLS = [
64
65
  function detect(cmd, args) {
65
66
  const res = spawnSync(cmd, args, { encoding: 'utf8' });
66
67
  if (res.error && res.error.code === 'ENOENT')
67
- return { ok: false };
68
+ return { ok: false, version: null };
68
69
  const version = (res.stdout || res.stderr || '').trim().split('\n')[0] || 'instalado';
69
70
  return { ok: true, version };
70
71
  }
72
+ /** Sondar e imprimir eram uma coisa só; o ramo `--json` precisa do resultado sem o texto. */
73
+ function detectTools() {
74
+ return TOOLS.map((tool) => {
75
+ const [cmd, args] = tool.probe;
76
+ const { ok, version } = detect(cmd, args);
77
+ return { name: tool.name, role: tool.role, gate: tool.gate, install: tool.install, ok, version };
78
+ });
79
+ }
71
80
  const TAG = {
72
81
  ok: 'OK ',
73
82
  warn: 'AVISO',
@@ -91,43 +100,51 @@ function printCore(results) {
91
100
  console.log('');
92
101
  }
93
102
  }
94
- function printTools() {
103
+ function printTools(tools) {
95
104
  console.log(`— ${BUCKET_LABEL.optional} — potencializam o harness, nunca travam (ADR-0018)\n`);
96
105
  let installed = 0;
97
- for (const tool of TOOLS) {
98
- const [cmd, args] = tool.probe;
99
- const { ok, version } = detect(cmd, args);
100
- if (ok)
106
+ for (const tool of tools) {
107
+ if (tool.ok)
101
108
  installed += 1;
102
- console.log(`${ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
109
+ console.log(`${tool.ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${tool.ok ? tool.version : '(ausente)'}`);
103
110
  console.log(` papel: ${tool.role}`);
104
111
  console.log(` gate: ${tool.gate}`);
105
- if (!ok)
112
+ if (!tool.ok)
106
113
  console.log(` instalar: ${tool.install}`);
107
114
  console.log('');
108
115
  }
109
- console.log(`${installed}/${TOOLS.length} ferramentas disponíveis.`);
116
+ console.log(`${installed}/${tools.length} ferramentas disponíveis.`);
110
117
  console.log('Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.\n');
111
118
  }
112
119
  /** Num projeto (fora do repo do framework): a IA, os hooks e o MCP estão ligados a ele? */
113
- function printProject() {
120
+ function collectProject() {
114
121
  const cwd = process.cwd();
115
122
  if (isInsideFrameworkRepo(cwd) || !fs.existsSync(path.join(cwd, 'AGENTS.md')))
116
123
  return null;
117
- console.log('Projeto — a IA enxerga o Forja aqui? (forja project:wire --check)\n');
118
124
  const checks = checkProjectWiring(cwd, { commands: COMMANDS });
119
- for (const c of checks)
125
+ return { status: checks.some((c) => c.status === 'fail') ? 'fail' : checks.some((c) => c.status === 'warn') ? 'warn' : 'ok', checks };
126
+ }
127
+ function printProject(project) {
128
+ if (project === null)
129
+ return null;
130
+ console.log('Projeto — a IA enxerga o Forja aqui? (forja project:wire --check)\n');
131
+ for (const c of project.checks)
120
132
  console.log(`${TAG[c.status]} ${c.id.padEnd(13)} ${c.detail}`);
121
133
  console.log('');
122
- return checks.some((c) => c.status === 'fail') ? 'fail' : checks.some((c) => c.status === 'warn') ? 'warn' : 'ok';
134
+ return project.status;
123
135
  }
124
136
  async function main() {
125
- console.log('\nForja doctor\n');
137
+ const asJson = process.argv.includes('--json');
126
138
  const core = await runChecks();
139
+ const tools = detectTools();
140
+ const project = collectProject();
141
+ if (asJson)
142
+ emitJson(core, project, tools);
143
+ console.log('\nForja doctor\n');
127
144
  printCore(core);
128
- const project = printProject();
129
- printTools();
130
- if (project === 'fail') {
145
+ const projectVerdict = printProject(project);
146
+ printTools(tools);
147
+ if (projectVerdict === 'fail') {
131
148
  console.log('Projeto desconectado da IA — corrija com: forja project:wire');
132
149
  process.exit(1);
133
150
  }
@@ -147,4 +164,28 @@ async function main() {
147
164
  }
148
165
  console.log('Núcleo saudável.');
149
166
  }
167
+ /**
168
+ * O registry anuncia `tools:doctor [--json]` e o script ignorava a flag: quem pedia JSON recebia o
169
+ * texto humano de volta. Mesmo contrato do ADR-0082 (um objeto no stdout, diagnóstico no stderr) e
170
+ * os mesmos exit codes do ramo de texto — 1 para núcleo quebrado ou projeto desconectado.
171
+ */
172
+ function emitJson(core, project, tools) {
173
+ if (project?.status === 'fail')
174
+ return emitError('Projeto desconectado da IA — corrija com: forja project:wire', { code: 'PROJECT_UNWIRED' });
175
+ const criticas = core.filter((r) => r.status === 'fail' && r.severity === 'critical');
176
+ if (criticas.length > 0) {
177
+ return emitError(`Núcleo quebrado — ${criticas.length} ${criticas.length === 1 ? 'falha' : 'falhas'} crítica(s)`, {
178
+ code: 'CORE_UNHEALTHY',
179
+ detail: criticas.map((r) => `${r.id}: ${r.fix || 'sem correção automática'}`).join('\n'),
180
+ });
181
+ }
182
+ return emitOk({
183
+ verdict: worstStatus(core),
184
+ core: core.map((r) => ({ id: r.id, status: r.status, severity: r.severity ?? null, detail: r.detail ?? null, fix: r.fix ?? null })),
185
+ ...(project === null ? {} : { project: { status: project.status, checks: project.checks } }),
186
+ tools,
187
+ toolsAvailable: tools.filter((tool) => tool.ok).length,
188
+ toolsTotal: tools.length,
189
+ });
190
+ }
150
191
  main();