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
@@ -1,137 +1,20 @@
1
- # Billing Domain Context
1
+ # Billing — contexto
2
2
 
3
- ## O que é Billing neste SaaS?
3
+ Cada organização tem uma **assinatura** de um **plano** (`free`, `pro`, `enterprise`). O período
4
+ de cobrança é o mês civil em UTC. Uma **fatura** cobra um período de uma assinatura.
4
5
 
5
- Billing cuida de:
6
- 1. Processar pagamentos (mock Stripe para MVP)
7
- 2. Gerar invoices
8
- 3. Registrar transações
9
- 4. Retry policy para falhas
10
- 5. Webhooks para eventos de billing
6
+ ## Regras
11
7
 
12
- ## Fluxo de Pagamento
8
+ - Preços e limites estão em `src/billing/domain/plan.ts`, em centavos inteiros. O valor da fatura
9
+ vem dali, nunca do cliente.
10
+ - Transições: `free → pro | enterprise`, `pro → free | enterprise`; `enterprise` é contratual
11
+ (mudanças fora da API). Transição proibida responde 422 e não altera nada.
12
+ - Mudar o plano é só da `owner`.
13
+ - Uma fatura por organização e período: emitir de novo devolve a mesma (índice único no banco).
14
+ Valor zero nasce `paid`; o resto nasce `open` até o gateway confirmar.
15
+ - Fatura de outra organização responde 404 (não 403: não confirma que existe).
13
16
 
14
- ```
15
- Usuário faz upgrade
16
- ↓
17
- Billing Agent recebe request
18
- ↓
19
- Validar payment method (card)
20
- ↓
21
- Chamar payment gateway (mock Stripe)
22
- ↓
23
- [Sucesso?]
24
- SIM → Criar invoice, registrar transação
25
- Enviar email de receipt
26
- Webhook callback
27
- NÃO → Retry logic (3 tentativas em 14 dias)
28
- Notificar usuário
29
- Tentar method alternativo
30
- ```
17
+ ## Onde está
31
18
 
32
- ## Payment Gateway Mock
33
-
34
- Para MVP, simulamos Stripe com:
35
- - Status: "succeeded" (90%) ou "failed" (10%)
36
- - Transações em banco de dados
37
- - Invoice generation automática
38
-
39
- ```typescript
40
- // Mock Stripe response
41
- {
42
- "id": "pi_1234567890",
43
- "amount": 9900,
44
- "currency": "usd",
45
- "status": "succeeded",
46
- "payment_method": {
47
- "type": "card",
48
- "card": { "last4": "4242", "brand": "visa" }
49
- },
50
- "created": 1705330200
51
- }
52
- ```
53
-
54
- ## Invoice Structure
55
-
56
- ```json
57
- {
58
- "id": "inv_xyz",
59
- "organizationId": "org-uuid",
60
- "invoiceNumber": "INV-2024-001",
61
- "amount": 99.00,
62
- "currency": "usd",
63
- "status": "paid",
64
- "description": "Pro Plan - January 2024",
65
- "items": [
66
- {
67
- "description": "Pro Plan",
68
- "quantity": 1,
69
- "unitPrice": 99.00,
70
- "amount": 99.00
71
- },
72
- {
73
- "description": "Additional User (4 seats)",
74
- "quantity": 4,
75
- "unitPrice": 10.00,
76
- "amount": 40.00
77
- }
78
- ],
79
- "issuedAt": "2024-01-01T00:00:00Z",
80
- "dueDate": "2024-01-15T00:00:00Z",
81
- "paidAt": "2024-01-01T10:30:00Z"
82
- }
83
- ```
84
-
85
- ## Regras de Negócio
86
-
87
- 1. **Retry Policy**:
88
- - 1ª tentativa: Imediato
89
- - 2ª tentativa: 3 dias depois
90
- - 3ª tentativa: 10 dias depois
91
- - Após 3 falhas: Suspender acc, enviar notificação
92
-
93
- 2. **Invoice Generation**:
94
- - Automático após pagamento bem-sucedido
95
- - Inclui subscription + add-ons (extra seats)
96
- - PDF gerado async (futura)
97
-
98
- 3. **Refund Policy**:
99
- - Dentro de 14 dias: Full refund
100
- - Após 14 dias: Pro-rata refund
101
- - Processado em 5-7 dias
102
-
103
- 4. **Tax Calculation** (Futura):
104
- - US: Sales tax por estado
105
- - EU: VAT aplicado
106
- - B2B: Reverse charge
107
-
108
- 5. **Currency Handling**:
109
- - MVP: USD apenas
110
- - Futuro: Multi-currency com taxa de câmbio
111
-
112
- ## Métricas Importantes
113
-
114
- - **Failed payment rate**: % de pagamentos rejeitados
115
- - **Churn via failed payment**: % de cancelamentos por payment failure
116
- - **Refund rate**: % de refunds vs total transactions
117
- - **Invoice delivery**: % enviados < 1 min
118
-
119
- ## Status Atual
120
-
121
- - ✅ Invoice entity
122
- - ✅ Payment mock (Stripe-like)
123
- - ✅ Transaction history
124
- - ✅ Invoice generation
125
- - 🚧 PDF generation
126
- - 🚧 Real Stripe integration
127
- - 🚧 Webhook handling
128
- - 🚧 Tax calculation
129
- - 🚧 Multi-currency
130
-
131
- ## Próximos Steps
132
-
133
- 1. Implementar real Stripe integration
134
- 2. Adicionar webhook handlers
135
- 3. Gerar PDFs de invoices
136
- 4. Implementar tax calculation
137
- 5. Adicionar refund endpoints
19
+ `src/billing/domain/` (planos, agregado `Subscription`, portas) ·
20
+ `application/billing.service.ts` · `adapters/persistence/` (TypeORM).
@@ -0,0 +1,20 @@
1
+ # Identity — contexto
2
+
3
+ **Organização** é o tenant: tudo que pertence a um cliente carrega o `tenantId` dela. Uma
4
+ **pessoa usuária** pertence a exatamente uma organização e tem papéis: `owner` (quem criou;
5
+ decide o plano), `admin` (gerencia membros e faturas), `member`.
6
+
7
+ ## Regras
8
+
9
+ - Cadastro cria a organização e a dona na mesma transação. O slug deriva do nome; se já existe,
10
+ ganha um sufixo aleatório.
11
+ - E-mail é único no sistema inteiro, comparado em minúsculas.
12
+ - Senha: mínimo 12 caracteres com minúscula, maiúscula e dígito; guardada com scrypt.
13
+ - Login errado e e-mail inexistente dão a mesma resposta, no mesmo tempo.
14
+ - Access token (15 min) e refresh token (7 dias) usam segredos distintos; um não vale como o outro.
15
+ O refresh relê a pessoa usuária: desativada, não renova.
16
+
17
+ ## Onde está
18
+
19
+ `src/identity/domain/` (modelo e porta) · `application/auth.service.ts` (casos de uso) ·
20
+ `src/platform/auth/` (tokens, guards, papéis).
@@ -44,23 +44,22 @@ forja project:new meu-projeto # e use boilerplates/01-api-rest/ como arquitetu
44
44
  ---
45
45
 
46
46
  ### 💼 2. SaaS
47
- **Para**: Aplicações multi-tenant, subscriptions, billing
47
+ **Para**: SaaS B2B multi-tenant com assinatura e faturamento
48
48
 
49
49
  ```bash
50
- forja project:new meu-projeto # e use boilerplates/02-saas-starter/ como arquitetura de referência
50
+ forja project:new meu-projeto --template saas-starter # template validado (NestJS 12, Vitest)
51
51
  ```
52
52
 
53
53
  **Inclui**:
54
- - Autenticação com planos
55
- - Subscription management
56
- - Billing mock
57
- - Organização multi-tenant
58
- - Role-based access control
59
- - Testes
54
+ - Organização = tenant; o tenant vem sempre do token, recurso de outro tenant responde 404
55
+ - Cadastro, login e refresh (scrypt, access e refresh com segredos distintos), papéis owner/admin/member
56
+ - Planos com transições validadas no domínio, preço em centavos vindo da tabela (nunca do cliente)
57
+ - Fatura mensal idempotente por período; gateway de pagamento fica como adapter seu
58
+ - A API não sobe sem os segredos configurados (nada de segredo padrão)
60
59
 
61
- **Use quando**: Construir SaaS com múltiplos clientes, subscriptions
60
+ **Use quando**: Construir SaaS com múltiplos clientes, papéis e assinaturas
62
61
 
63
- [Abrir 📂](./02-saas)
62
+ [Abrir 📂](./02-saas-starter)
64
63
 
65
64
  ---
66
65
 
@@ -57,5 +57,4 @@ export declare function parseLegacyCommandInput(command: string, args: readonly
57
57
  readonly payload: InputRecord;
58
58
  };
59
59
  export declare function executeCliCapability(runtime: CliCapabilityRuntime, capabilityId: CapabilityId, payload: unknown, correlationId?: string): Promise<ExecutionResult>;
60
- export declare function normalizeCliResult(result: ExecutionResult): ExecutionResult;
61
60
  export {};
@@ -1,7 +1,7 @@
1
1
  import { randomUUID } from 'node:crypto';
2
2
  import { spawnSync } from 'node:child_process';
3
3
  import { CONTRACT_VERSION, } from '../../../packages/contracts/src/index.js';
4
- import { CapabilityRegistry, } from '../../../packages/core/src/index.js';
4
+ import { CapabilityRegistry, CapabilityExecutionFailure, } from '../../../packages/core/src/index.js';
5
5
  import { PolicyEngine } from '../../../packages/policy/src/index.js';
6
6
  import { COMMANDS, resolveScript } from '../../../lib/core/registry.js';
7
7
  import { GraphIndexer } from '../../../packages/graph/src/index.js';
@@ -28,8 +28,7 @@ export const CLI_CAPABILITY_SPECS = [
28
28
  permissions: ['read'],
29
29
  risk: 'low',
30
30
  sideEffects: [],
31
- params: [],
32
- validateInput: emptyInput,
31
+ params: [{ name: 'json', kind: 'flag' }],
33
32
  },
34
33
  {
35
34
  id: 'code.impact',
@@ -130,14 +129,20 @@ export const CLI_CAPABILITY_SPECS = [
130
129
  {
131
130
  id: 'code.context',
132
131
  command: 'code:context',
133
- description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code).',
132
+ description: 'Pacote de contexto mínimo de um domínio (o mapa; + código com --code, fatia inteira com --full).',
134
133
  categories: ['read'],
135
134
  permissions: ['read'],
136
135
  risk: 'low',
137
136
  sideEffects: [],
137
+ // Cada flag que `usage` anuncia tem que estar aqui: o roteador rebuilda o argv a partir destes
138
+ // params, e o que não é declarado é descartado em silêncio — `--full` existir no help e não chegar
139
+ // ao script é o pior tipo de flag (o usuário jura que pediu).
138
140
  params: [
139
141
  { name: 'domain', kind: 'positional' },
142
+ { name: 'query', kind: 'positional' },
140
143
  { name: 'code', kind: 'flag' },
144
+ { name: 'full', kind: 'flag' },
145
+ { name: 'project', kind: 'flag-value', flag: '--project' },
141
146
  ],
142
147
  },
143
148
  {
@@ -218,7 +223,7 @@ export const CLI_CAPABILITY_SPECS = [
218
223
  permissions: ['read'],
219
224
  risk: 'low',
220
225
  sideEffects: [],
221
- params: [],
226
+ params: [{ name: 'json', kind: 'flag' }],
222
227
  },
223
228
  {
224
229
  id: 'forja.next',
@@ -228,7 +233,32 @@ export const CLI_CAPABILITY_SPECS = [
228
233
  permissions: ['read'],
229
234
  risk: 'low',
230
235
  sideEffects: [],
231
- params: [],
236
+ params: [{ name: 'json', kind: 'flag' }],
237
+ },
238
+ // --- SPEC-057: os dois relatórios read-only que só existiam como script (dashboard/MCP) ---
239
+ {
240
+ id: 'spec.trace',
241
+ command: 'spec:trace',
242
+ description: 'Critérios de aceite × testes que os citam: cobertos, sem teste e órfãos.',
243
+ categories: ['read'],
244
+ permissions: ['read'],
245
+ risk: 'low',
246
+ sideEffects: [],
247
+ params: [
248
+ { name: 'slug', kind: 'positional' },
249
+ { name: 'strict', kind: 'flag' },
250
+ { name: 'json', kind: 'flag' },
251
+ ],
252
+ },
253
+ {
254
+ id: 'cost.economy',
255
+ command: 'cost:economy',
256
+ description: 'Custo real acumulado (USD) das execuções LLM registradas, por modelo.',
257
+ categories: ['read', 'database'],
258
+ permissions: ['read'],
259
+ risk: 'low',
260
+ sideEffects: [],
261
+ params: [{ name: 'json', kind: 'flag' }],
232
262
  },
233
263
  ];
234
264
  export const CLI_COMMAND_TO_CAPABILITY = Object.freeze(Object.fromEntries(CLI_CAPABILITY_SPECS.map((spec) => [spec.command, spec.id])));
@@ -298,7 +328,7 @@ export function parseLegacyCommandInput(command, args) {
298
328
  export async function executeCliCapability(runtime, capabilityId, payload, correlationId) {
299
329
  const definition = runtime.registry.describe(capabilityId);
300
330
  const categories = categoriesFor(definition.id);
301
- const result = await runtime.registry.execute({
331
+ return runtime.registry.execute({
302
332
  input: { capabilityId, payload },
303
333
  agent: runtime.agent,
304
334
  policy: runtime.policy,
@@ -307,23 +337,6 @@ export async function executeCliCapability(runtime, capabilityId, payload, corre
307
337
  categories,
308
338
  files: [],
309
339
  });
310
- return normalizeCliResult(result);
311
- }
312
- export function normalizeCliResult(result) {
313
- if (result.status !== 'succeeded' || result.output === undefined || !isRecord(result.output.payload))
314
- return result;
315
- const exitCode = result.output.payload.exitCode;
316
- if (typeof exitCode !== 'number' || exitCode === 0)
317
- return result;
318
- return {
319
- ...result,
320
- status: 'failed',
321
- error: {
322
- code: 'LEGACY_COMMAND_FAILED',
323
- message: `Legacy command exited with status ${exitCode}`,
324
- retryable: false,
325
- },
326
- };
327
340
  }
328
341
  function registerCliCapability(registry, runner, spec) {
329
342
  const now = new Date().toISOString();
@@ -347,6 +360,7 @@ function registerCliCapability(registry, runner, spec) {
347
360
  };
348
361
  const registration = {
349
362
  definition,
363
+ categories: spec.categories,
350
364
  validateInput: spec.validateInput ?? makeValidator(spec.params),
351
365
  validateOutput: validateCliPayload,
352
366
  handler: async (input) => {
@@ -360,11 +374,15 @@ function registerCliCapability(registry, runner, spec) {
360
374
  capturedAt,
361
375
  status: result.exitCode === 0 ? 'verified' : 'contradicted',
362
376
  };
363
- return {
377
+ const output = {
364
378
  capabilityId: spec.id,
365
379
  payload: { command: spec.command, args, ...result },
366
380
  evidence: [evidence],
367
381
  };
382
+ if (result.exitCode !== 0) {
383
+ throw new CapabilityExecutionFailure({ code: 'LEGACY_COMMAND_FAILED', message: `Legacy command exited with status ${result.exitCode}`, retryable: false }, output);
384
+ }
385
+ return output;
368
386
  },
369
387
  };
370
388
  registry.register(registration);
@@ -372,13 +390,6 @@ function registerCliCapability(registry, runner, spec) {
372
390
  function categoriesFor(id) {
373
391
  return CLI_CAPABILITY_SPECS.find((spec) => spec.id === id)?.categories ?? ['read'];
374
392
  }
375
- function emptyInput(value) {
376
- if (value === undefined || value === null)
377
- return {};
378
- if (!isRecord(value) || Object.keys(value).length > 0)
379
- throw new Error('Input must be an empty object');
380
- return {};
381
- }
382
393
  function validateCodeImpactInput(value) {
383
394
  const input = requireRecord(value);
384
395
  const symbol = input.symbol;
@@ -2,7 +2,9 @@
2
2
  import { buildApprovalDecisionBody } from '../approval';
3
3
  // @ts-expect-error Next resolves the adjacent TypeScript helper.
4
4
  import { isCallerAuthorized, matchesAllowedPrefix } from '../guard';
5
- const allowedPrefixes = ['/control-plane/metrics', '/observability/observations', '/events/stream', '/executions/', '/graph/query', '/graph/impact', '/approvals'];
5
+ // @ts-expect-error Next resolves the adjacent TypeScript helper.
6
+ import { capabilityIdFromExecutePath, isReadOnlyCapability } from '../capabilities';
7
+ const allowedPrefixes = ['/control-plane/metrics', '/observability/observations', '/events', '/executions/', '/graph/query', '/graph/impact', '/approvals', '/capabilities'];
6
8
  export async function GET(request, context) { return forward(request, await context.params, 'GET'); }
7
9
  export async function POST(request, context) { return forward(request, await context.params, 'POST'); }
8
10
  async function forward(request, params, method) {
@@ -16,6 +18,19 @@ async function forward(request, params, method) {
16
18
  return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: 'Dashboard route is not allowed' } }), { status: 403, headers: { 'content-type': 'application/json' } });
17
19
  const backend = process.env.FORJA_API_URL ?? 'http://localhost:3000';
18
20
  const token = process.env.FORJA_API_TOKEN;
21
+ // ADR-0022, condição de retomada #2: o que o painel alcança é derivado do que o servidor declara,
22
+ // nunca de uma lista escrita à mão aqui. O dashboard anterior mantinha allowlist própria e por ela
23
+ // rodava comando que não passava pelos gates nem aparecia na auditoria; este portão existe para
24
+ // que executar pela UI seja o mesmo caminho auditado de sempre, e só para capacidades que não
25
+ // escrevem. Falha fechada: catálogo que não responde é 403, não é liberado.
26
+ if (method === 'POST') {
27
+ const capabilityId = capabilityIdFromExecutePath(path);
28
+ if (capabilityId !== null) {
29
+ const surface = await readCapabilitySurface(`${backend}/api/capabilities`, token, capabilityId);
30
+ if (surface === null || !isReadOnlyCapability(surface))
31
+ return new Response(JSON.stringify({ error: { code: 'FORBIDDEN', message: `Capability is not read-only: ${capabilityId}` } }), { status: 403, headers: { 'content-type': 'application/json' } });
32
+ }
33
+ }
19
34
  const headers = new Headers({ accept: request.headers.get('accept') ?? 'application/json' });
20
35
  if (token !== undefined)
21
36
  headers.set('authorization', `Bearer ${token}`);
@@ -41,3 +56,21 @@ async function forward(request, params, method) {
41
56
  responseHeaders.set('cache-control', cacheControl);
42
57
  return new Response(response.body, { status: response.status, headers: responseHeaders });
43
58
  }
59
+ /** A definição que o servidor declara para a capacidade, ou null quando o catálogo não responde. */
60
+ async function readCapabilitySurface(catalogUrl, token, id) {
61
+ const headers = new Headers({ accept: 'application/json' });
62
+ if (token !== undefined)
63
+ headers.set('authorization', `Bearer ${token}`);
64
+ try {
65
+ const catalog = await fetch(catalogUrl, { headers, cache: 'no-store' });
66
+ if (!catalog.ok)
67
+ return null;
68
+ const definitions = await catalog.json();
69
+ if (!Array.isArray(definitions))
70
+ return null;
71
+ return definitions.find((definition) => definition.id === id) ?? null;
72
+ }
73
+ catch {
74
+ return null;
75
+ }
76
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Pure helpers backing the dashboard's read-only capability access, same pattern as `guard.ts`
3
+ * and `approval.ts`: no Next types in here, so the rules are unit-testable directly.
4
+ *
5
+ * ADR-0022 congelou o dashboard anterior porque ele mantinha uma allowlist de comandos própria,
6
+ * paralela ao registry — e nela existia comando que o registry não tinha, executado por fora dos
7
+ * gates e da trilha de auditoria. A condição de retomada #2 era derivar a exposição do registry.
8
+ * Aqui não há lista: o que o painel pode executar é decidido pelo que o próprio servidor declara
9
+ * em `/api/capabilities`, filtrado pela regra abaixo.
10
+ */
11
+ /** O mínimo de uma `CapabilityDefinition` (packages/contracts) que a regra precisa. */
12
+ export interface CapabilitySurface {
13
+ readonly id: string;
14
+ readonly permissions: readonly string[];
15
+ readonly sideEffects: readonly string[];
16
+ }
17
+ /**
18
+ * Read-only de verdade: sem permissão de escrita e sem efeito colateral declarado. `risk` não
19
+ * entra na regra porque é julgamento do autor da capacidade, não um fato sobre o que ela toca —
20
+ * `context.budget` é risk low e ainda assim grava `context_run_record`. Definição que não declara
21
+ * os dois campos é recusada: o portão falha fechado, não por falta de evidência de que escreve.
22
+ */
23
+ export declare function isReadOnlyCapability(capability: CapabilitySurface | null): boolean;
24
+ /** `/capabilities/spec.validate/execute` → `spec.validate`; qualquer outra forma → null. */
25
+ export declare function capabilityIdFromExecutePath(pathname: string): string | null;
26
+ export declare function isCapabilityListPath(pathname: string): boolean;
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Pure helpers backing the dashboard's read-only capability access, same pattern as `guard.ts`
3
+ * and `approval.ts`: no Next types in here, so the rules are unit-testable directly.
4
+ *
5
+ * ADR-0022 congelou o dashboard anterior porque ele mantinha uma allowlist de comandos própria,
6
+ * paralela ao registry — e nela existia comando que o registry não tinha, executado por fora dos
7
+ * gates e da trilha de auditoria. A condição de retomada #2 era derivar a exposição do registry.
8
+ * Aqui não há lista: o que o painel pode executar é decidido pelo que o próprio servidor declara
9
+ * em `/api/capabilities`, filtrado pela regra abaixo.
10
+ */
11
+ /**
12
+ * Read-only de verdade: sem permissão de escrita e sem efeito colateral declarado. `risk` não
13
+ * entra na regra porque é julgamento do autor da capacidade, não um fato sobre o que ela toca —
14
+ * `context.budget` é risk low e ainda assim grava `context_run_record`. Definição que não declara
15
+ * os dois campos é recusada: o portão falha fechado, não por falta de evidência de que escreve.
16
+ */
17
+ export function isReadOnlyCapability(capability) {
18
+ if (capability === null)
19
+ return false;
20
+ if (!Array.isArray(capability.permissions) || !Array.isArray(capability.sideEffects))
21
+ return false;
22
+ if (capability.permissions.includes('write'))
23
+ return false;
24
+ return capability.sideEffects.length === 0;
25
+ }
26
+ /** `/capabilities/spec.validate/execute` → `spec.validate`; qualquer outra forma → null. */
27
+ export function capabilityIdFromExecutePath(pathname) {
28
+ const prefix = '/capabilities/';
29
+ const suffix = '/execute';
30
+ if (!pathname.startsWith(prefix) || !pathname.endsWith(suffix))
31
+ return null;
32
+ const id = pathname.slice(prefix.length, -suffix.length);
33
+ if (id.length === 0 || id.includes('/'))
34
+ return null;
35
+ return id;
36
+ }
37
+ export function isCapabilityListPath(pathname) {
38
+ return pathname === '/capabilities';
39
+ }