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
@@ -0,0 +1,19 @@
1
+ import { normalizeEmail, toSlug } from './model.js';
2
+
3
+ describe('identidade', () => {
4
+ it.each([
5
+ { name: 'minúsculas e hífens', input: 'Minha Empresa', want: 'minha-empresa' },
6
+ { name: 'remove acentos', input: 'Ação & Cia', want: 'acao-cia' },
7
+ { name: 'apara separadores nas pontas', input: ' --Loja-- ', want: 'loja' },
8
+ ])('slug: $name', ({ input, want }) => {
9
+ expect(toSlug(input)).toBe(want);
10
+ });
11
+
12
+ it('slug sem letras nem números é recusado', () => {
13
+ expect(() => toSlug('!!!')).toThrow();
14
+ });
15
+
16
+ it('e-mail é comparado em minúsculas e sem espaços', () => {
17
+ expect(normalizeEmail(' Ana@Exemplo.COM ')).toBe('ana@exemplo.com');
18
+ });
19
+ });
@@ -0,0 +1,42 @@
1
+ import type { Role } from '../../platform/auth/principal.js';
2
+
3
+ export interface Organization {
4
+ readonly id: string;
5
+ readonly tenantId: string;
6
+ readonly name: string;
7
+ readonly slug: string;
8
+ readonly ownerId: string;
9
+ }
10
+
11
+ export interface User {
12
+ readonly id: string;
13
+ readonly tenantId: string;
14
+ readonly email: string;
15
+ readonly passwordHash: string;
16
+ readonly roles: readonly Role[];
17
+ readonly active: boolean;
18
+ }
19
+
20
+ /** E-mail é a identidade de login: global (o login não sabe o tenant), comparado em minúsculas. */
21
+ export function normalizeEmail(email: string): string {
22
+ return email.trim().toLowerCase();
23
+ }
24
+
25
+ export function toSlug(name: string): string {
26
+ const slug = name.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
27
+ if (!slug) throw new Error('Nome da organização precisa ter letras ou números');
28
+ return slug.slice(0, 60);
29
+ }
30
+
31
+ /** Portas de persistência: o domínio declara, os adaptadores TypeORM implementam. */
32
+ export interface IdentityRepository {
33
+ findUserByEmail(email: string): Promise<User | null>;
34
+ findUserById(id: string, tenantId: string): Promise<User | null>;
35
+ listUsers(tenantId: string): Promise<User[]>;
36
+ findOrganization(tenantId: string): Promise<Organization | null>;
37
+ slugTaken(slug: string): Promise<boolean>;
38
+ /** Cria a organização e o dono numa transação só: nunca um sem o outro. */
39
+ createTenant(org: Organization, owner: User): Promise<void>;
40
+ }
41
+
42
+ export const IDENTITY_REPOSITORY = Symbol('IDENTITY_REPOSITORY');
@@ -0,0 +1,17 @@
1
+ import { hashPassword, verifyPassword } from './password.js';
2
+
3
+ describe('senha (scrypt)', () => {
4
+ it('confere a senha certa e recusa a errada', async () => {
5
+ const hash = await hashPassword('Correta-Senha-123');
6
+ expect(await verifyPassword('Correta-Senha-123', hash)).toBe(true);
7
+ expect(await verifyPassword('correta-senha-123', hash)).toBe(false);
8
+ });
9
+
10
+ it('gera hashes diferentes para a mesma senha (salt)', async () => {
11
+ expect(await hashPassword('Igual-Senha-123')).not.toBe(await hashPassword('Igual-Senha-123'));
12
+ });
13
+
14
+ it('recusa hash malformado sem lançar', async () => {
15
+ expect(await verifyPassword('x', 'bcrypt$abc')).toBe(false);
16
+ });
17
+ });
@@ -0,0 +1,26 @@
1
+ import { randomBytes, scrypt, timingSafeEqual, type ScryptOptions } from 'node:crypto';
2
+
3
+ /**
4
+ * Hash de senha com scrypt (node:crypto): sem dependência nativa para instalar. Formato:
5
+ * `scrypt$N$r$p$<salt base64>$<hash base64>`, para os parâmetros poderem subir sem invalidar hashes antigos.
6
+ */
7
+ const PARAMS = { N: 2 ** 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 } as const;
8
+ const KEYLEN = 64;
9
+
10
+ function derive(password: string, salt: Buffer, options: ScryptOptions): Promise<Buffer> {
11
+ return new Promise((resolve, reject) => scrypt(password.normalize('NFKC'), salt, KEYLEN, options, (err, key) => (err ? reject(err) : resolve(key))));
12
+ }
13
+
14
+ export async function hashPassword(password: string): Promise<string> {
15
+ const salt = randomBytes(16);
16
+ const key = await derive(password, salt, PARAMS);
17
+ return ['scrypt', PARAMS.N, PARAMS.r, PARAMS.p, salt.toString('base64'), key.toString('base64')].join('$');
18
+ }
19
+
20
+ export async function verifyPassword(password: string, stored: string): Promise<boolean> {
21
+ const [scheme, n, r, p, salt, hash] = stored.split('$');
22
+ if (scheme !== 'scrypt' || !salt || !hash) return false;
23
+ const expected = Buffer.from(hash, 'base64');
24
+ const key = await derive(password, Buffer.from(salt, 'base64'), { N: Number(n), r: Number(r), p: Number(p), maxmem: PARAMS.maxmem });
25
+ return key.length === expected.length && timingSafeEqual(key, expected);
26
+ }
@@ -0,0 +1,12 @@
1
+ import { Module } from '@nestjs/common';
2
+ import { AuthService } from './application/auth.service.js';
3
+ import { IDENTITY_REPOSITORY } from './domain/model.js';
4
+ import { TypeOrmIdentityRepository } from './adapters/persistence/typeorm-identity.repository.js';
5
+ import { AuthController, IdentityController } from './adapters/http/identity.controller.js';
6
+
7
+ @Module({
8
+ controllers: [AuthController, IdentityController],
9
+ providers: [AuthService, { provide: IDENTITY_REPOSITORY, useClass: TypeOrmIdentityRepository }],
10
+ exports: [IDENTITY_REPOSITORY],
11
+ })
12
+ export class IdentityModule {}
@@ -1,26 +1,26 @@
1
- import { NestFactory } from '@nestjs/core';
1
+ import 'reflect-metadata';
2
+ import { existsSync } from 'node:fs';
2
3
  import { ValidationPipe } from '@nestjs/common';
3
- import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
4
- import { AppModule } from './app.module';
4
+ import { NestFactory } from '@nestjs/core';
5
+ import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
6
+ import { AppModule } from './app.module.js';
7
+ import { APP_CONFIG, type AppConfig } from './platform/config.js';
5
8
 
6
- async function bootstrap() {
9
+ async function bootstrap(): Promise<void> {
10
+ // .env é opcional: em produção as variáveis vêm do ambiente.
11
+ if (existsSync('.env')) process.loadEnvFile('.env');
7
12
  const app = await NestFactory.create(AppModule);
8
-
9
- app.useGlobalPipes(new ValidationPipe({ transform: true }));
10
13
  app.setGlobalPrefix('api');
14
+ // whitelist + forbidNonWhitelisted: campos fora do DTO são rejeitados (nada de atribuição em massa).
15
+ app.useGlobalPipes(new ValidationPipe({ whitelist: true, forbidNonWhitelisted: true, transform: true }));
16
+ app.enableShutdownHooks();
11
17
 
12
- const config = new DocumentBuilder()
13
- .setTitle('SaaS Starter API')
14
- .setDescription('Multi-tenant SaaS platform with auth, subscriptions & billing')
15
- .setVersion('1.0.0')
16
- .addBearerAuth()
17
- .build();
18
-
19
- const document = SwaggerModule.createDocument(app, config);
20
- SwaggerModule.setup('api/docs', app, document);
21
-
22
- await app.listen(process.env.PORT || 3000);
23
- console.log(`🚀 Server running on http://localhost:${process.env.PORT || 3000}`);
18
+ const config = app.get<AppConfig>(APP_CONFIG);
19
+ if (!config.production) {
20
+ const doc = new DocumentBuilder().setTitle('SaaS Starter API').setVersion('0.1.0').addBearerAuth().build();
21
+ SwaggerModule.setup('api/docs', app, SwaggerModule.createDocument(app, doc));
22
+ }
23
+ await app.listen(config.port);
24
24
  }
25
25
 
26
- bootstrap();
26
+ await bootstrap();
@@ -0,0 +1,17 @@
1
+ import { Injectable, UnauthorizedException, type CanActivate, type ExecutionContext } from '@nestjs/common';
2
+ import type { AuthenticatedRequest } from './principal.js';
3
+ import { TokenService } from './token.service.js';
4
+
5
+ @Injectable()
6
+ export class JwtAuthGuard implements CanActivate {
7
+ constructor(private readonly tokens: TokenService) {}
8
+
9
+ async canActivate(context: ExecutionContext): Promise<boolean> {
10
+ const request = context.switchToHttp().getRequest<AuthenticatedRequest>();
11
+ const header = request.headers.authorization;
12
+ const value = Array.isArray(header) ? header[0] : header;
13
+ if (!value?.startsWith('Bearer ')) throw new UnauthorizedException('Token ausente');
14
+ request.principal = await this.tokens.verifyAccess(value.slice('Bearer '.length));
15
+ return true;
16
+ }
17
+ }
@@ -0,0 +1,22 @@
1
+ import { createParamDecorator, type ExecutionContext } from '@nestjs/common';
2
+
3
+ export const ROLES = ['owner', 'admin', 'member'] as const;
4
+ export type Role = (typeof ROLES)[number];
5
+
6
+ /** Quem está chamando: vem só do token verificado, nunca do corpo da requisição. */
7
+ export interface Principal {
8
+ readonly userId: string;
9
+ readonly tenantId: string;
10
+ readonly roles: readonly Role[];
11
+ }
12
+
13
+ export interface AuthenticatedRequest {
14
+ principal?: Principal;
15
+ headers: Record<string, string | string[] | undefined>;
16
+ }
17
+
18
+ export const CurrentPrincipal = createParamDecorator((_: unknown, ctx: ExecutionContext): Principal => {
19
+ const principal = ctx.switchToHttp().getRequest<AuthenticatedRequest>().principal;
20
+ if (!principal) throw new Error('CurrentPrincipal usado em rota sem JwtAuthGuard');
21
+ return principal;
22
+ });
@@ -0,0 +1,23 @@
1
+ import { ForbiddenException, type ExecutionContext } from '@nestjs/common';
2
+ import { Reflector } from '@nestjs/core';
3
+ import { RolesGuard } from './roles.guard.js';
4
+ import type { Role } from './principal.js';
5
+
6
+ const ctx = (roles: Role[] | undefined): ExecutionContext => ({
7
+ getHandler: () => () => undefined,
8
+ getClass: () => class {},
9
+ switchToHttp: () => ({ getRequest: () => ({ principal: roles ? { userId: 'u', tenantId: 't', roles } : undefined }) }),
10
+ }) as unknown as ExecutionContext;
11
+
12
+ describe('RolesGuard', () => {
13
+ const guardFor = (required: Role[] | undefined) => new RolesGuard({ getAllAndOverride: () => required } as unknown as Reflector);
14
+
15
+ it('rota sem papéis exigidos libera qualquer autenticado', () => {
16
+ expect(guardFor(undefined).canActivate(ctx(['member']))).toBe(true);
17
+ });
18
+
19
+ it('libera quem tem um dos papéis e barra quem não tem', () => {
20
+ expect(guardFor(['owner', 'admin']).canActivate(ctx(['admin']))).toBe(true);
21
+ expect(() => guardFor(['owner']).canActivate(ctx(['member']))).toThrow(ForbiddenException);
22
+ });
23
+ });
@@ -0,0 +1,20 @@
1
+ import { ForbiddenException, Injectable, SetMetadata, type CanActivate, type ExecutionContext } from '@nestjs/common';
2
+ import { Reflector } from '@nestjs/core';
3
+ import type { AuthenticatedRequest, Role } from './principal.js';
4
+
5
+ const ROLES_KEY = 'roles';
6
+ export const RequireRoles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);
7
+
8
+ /** Use depois do JwtAuthGuard. Sem @RequireRoles na rota, qualquer usuário autenticado passa. */
9
+ @Injectable()
10
+ export class RolesGuard implements CanActivate {
11
+ constructor(private readonly reflector: Reflector) {}
12
+
13
+ canActivate(context: ExecutionContext): boolean {
14
+ const required = this.reflector.getAllAndOverride<Role[] | undefined>(ROLES_KEY, [context.getHandler(), context.getClass()]);
15
+ if (!required?.length) return true;
16
+ const roles = context.switchToHttp().getRequest<AuthenticatedRequest>().principal?.roles ?? [];
17
+ if (!required.some((role) => roles.includes(role))) throw new ForbiddenException('Permissão insuficiente');
18
+ return true;
19
+ }
20
+ }
@@ -0,0 +1,54 @@
1
+ import { Inject, Injectable, UnauthorizedException } from '@nestjs/common';
2
+ import { JwtService } from '@nestjs/jwt';
3
+ import { APP_CONFIG, type AppConfig } from '../config.js';
4
+ import { ROLES, type Principal, type Role } from './principal.js';
5
+
6
+ export interface TokenPair {
7
+ readonly accessToken: string;
8
+ readonly refreshToken: string;
9
+ }
10
+
11
+ interface Claims {
12
+ sub: string;
13
+ tid: string;
14
+ roles: Role[];
15
+ typ: 'access' | 'refresh';
16
+ }
17
+
18
+ /** Tokens de acesso (15 min) e de renovação (7 dias) com segredos distintos e tipo explícito. */
19
+ @Injectable()
20
+ export class TokenService {
21
+ constructor(
22
+ private readonly jwt: JwtService,
23
+ @Inject(APP_CONFIG) private readonly config: AppConfig,
24
+ ) {}
25
+
26
+ async issue(principal: Principal): Promise<TokenPair> {
27
+ const base = { sub: principal.userId, tid: principal.tenantId, roles: [...principal.roles] };
28
+ const [accessToken, refreshToken] = await Promise.all([
29
+ this.jwt.signAsync({ ...base, typ: 'access' }, { secret: this.config.jwtSecret, expiresIn: '15m' }),
30
+ this.jwt.signAsync({ ...base, typ: 'refresh' }, { secret: this.config.jwtRefreshSecret, expiresIn: '7d' }),
31
+ ]);
32
+ return { accessToken, refreshToken };
33
+ }
34
+
35
+ verifyAccess(token: string): Promise<Principal> {
36
+ return this.verify(token, this.config.jwtSecret, 'access');
37
+ }
38
+
39
+ verifyRefresh(token: string): Promise<Principal> {
40
+ return this.verify(token, this.config.jwtRefreshSecret, 'refresh');
41
+ }
42
+
43
+ private async verify(token: string, secret: string, typ: Claims['typ']): Promise<Principal> {
44
+ let claims: Claims;
45
+ try {
46
+ claims = await this.jwt.verifyAsync<Claims>(token, { secret });
47
+ } catch {
48
+ throw new UnauthorizedException('Token inválido ou expirado');
49
+ }
50
+ const roles = Array.isArray(claims.roles) ? claims.roles.filter((r): r is Role => (ROLES as readonly string[]).includes(r)) : [];
51
+ if (claims.typ !== typ || !claims.sub || !claims.tid) throw new UnauthorizedException('Token inválido ou expirado');
52
+ return { userId: claims.sub, tenantId: claims.tid, roles };
53
+ }
54
+ }
@@ -0,0 +1,18 @@
1
+ import { loadConfig } from './config.js';
2
+
3
+ const ok = { DATABASE_URL: 'postgres://x', JWT_SECRET: 'a'.repeat(32), JWT_REFRESH_SECRET: 'b'.repeat(32) };
4
+
5
+ describe('configuração', () => {
6
+ it('sem segredos a API não sobe (nada de segredo padrão)', () => {
7
+ expect(() => loadConfig({ DATABASE_URL: 'postgres://x' })).toThrow(/JWT_SECRET, JWT_REFRESH_SECRET/);
8
+ });
9
+
10
+ it('segredos curtos ou iguais são recusados', () => {
11
+ expect(() => loadConfig({ ...ok, JWT_SECRET: 'curto' })).toThrow(/32 caracteres/);
12
+ expect(() => loadConfig({ ...ok, JWT_REFRESH_SECRET: ok.JWT_SECRET })).toThrow(/diferentes/);
13
+ });
14
+
15
+ it('valores padrão para porta e moeda', () => {
16
+ expect(loadConfig(ok)).toMatchObject({ port: 3000, currency: 'BRL', production: false });
17
+ });
18
+ });
@@ -0,0 +1,33 @@
1
+ /**
2
+ * Configuração lida do ambiente uma vez, no boot. Segredos não têm valor padrão: sem eles a API não
3
+ * sobe, em vez de subir assinando tokens com um segredo conhecido.
4
+ */
5
+ export interface AppConfig {
6
+ readonly port: number;
7
+ readonly databaseUrl: string;
8
+ readonly jwtSecret: string;
9
+ readonly jwtRefreshSecret: string;
10
+ readonly currency: string;
11
+ readonly production: boolean;
12
+ }
13
+
14
+ export const APP_CONFIG = Symbol('APP_CONFIG');
15
+
16
+ export function loadConfig(env: Record<string, string | undefined> = process.env): AppConfig {
17
+ const missing = ['DATABASE_URL', 'JWT_SECRET', 'JWT_REFRESH_SECRET'].filter((k) => !env[k]);
18
+ if (missing.length) throw new Error(`Variáveis de ambiente obrigatórias ausentes: ${missing.join(', ')} (veja .env.example)`);
19
+ if (env.JWT_SECRET === env.JWT_REFRESH_SECRET) throw new Error('JWT_SECRET e JWT_REFRESH_SECRET precisam ser diferentes');
20
+ if ((env.JWT_SECRET ?? '').length < 32 || (env.JWT_REFRESH_SECRET ?? '').length < 32) {
21
+ throw new Error('JWT_SECRET e JWT_REFRESH_SECRET precisam ter pelo menos 32 caracteres');
22
+ }
23
+ const port = Number(env.PORT ?? 3000);
24
+ if (!Number.isInteger(port) || port <= 0) throw new Error(`PORT inválida: ${env.PORT}`);
25
+ return {
26
+ port,
27
+ databaseUrl: env.DATABASE_URL as string,
28
+ jwtSecret: env.JWT_SECRET as string,
29
+ jwtRefreshSecret: env.JWT_REFRESH_SECRET as string,
30
+ currency: env.BILLING_CURRENCY ?? 'BRL',
31
+ production: env.NODE_ENV === 'production',
32
+ };
33
+ }
@@ -0,0 +1,14 @@
1
+ import { Global, Module } from '@nestjs/common';
2
+ import { JwtModule } from '@nestjs/jwt';
3
+ import { APP_CONFIG, loadConfig } from './config.js';
4
+ import { TokenService } from './auth/token.service.js';
5
+ import { JwtAuthGuard } from './auth/jwt-auth.guard.js';
6
+ import { RolesGuard } from './auth/roles.guard.js';
7
+
8
+ @Global()
9
+ @Module({
10
+ imports: [JwtModule.register({})],
11
+ providers: [{ provide: APP_CONFIG, useFactory: () => loadConfig() }, TokenService, JwtAuthGuard, RolesGuard],
12
+ exports: [APP_CONFIG, TokenService, JwtAuthGuard, RolesGuard],
13
+ })
14
+ export class PlatformModule {}
@@ -0,0 +1,6 @@
1
+ {
2
+ "extends": "./tsconfig.json",
3
+ "compilerOptions": { "rootDir": "./src" },
4
+ "include": ["src"],
5
+ "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
6
+ }
@@ -1,28 +1,23 @@
1
1
  {
2
2
  "compilerOptions": {
3
- "module": "commonjs",
4
- "target": "ES2021",
5
- "lib": ["ES2021"],
6
- "declaration": true,
3
+ "module": "nodenext",
4
+ "moduleResolution": "nodenext",
5
+ "resolvePackageJsonExports": true,
6
+ "esModuleInterop": true,
7
+ "isolatedModules": true,
8
+ "declaration": false,
9
+ "removeComments": true,
10
+ "emitDecoratorMetadata": true,
11
+ "experimentalDecorators": true,
12
+ "allowSyntheticDefaultImports": true,
13
+ "target": "ES2023",
14
+ "sourceMap": true,
7
15
  "outDir": "./dist",
8
- "baseUrl": "./",
16
+ "rootDir": ".",
9
17
  "incremental": true,
10
18
  "skipLibCheck": true,
11
- "strictNullChecks": true,
19
+ "strict": true,
12
20
  "strictPropertyInitialization": false,
13
- "strictBindCallApply": true,
14
- "forceConsistentCasingInFileNames": true,
15
- "resolveJsonModule": true,
16
- "declaration": true,
17
- "declarationMap": true,
18
- "sourceMap": true,
19
- "paths": {
20
- "@/*": ["src/*"],
21
- "@modules/*": ["src/modules/*"],
22
- "@common/*": ["src/common/*"],
23
- "@config/*": ["src/config/*"]
24
- }
25
- },
26
- "include": ["src/**/*"],
27
- "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
21
+ "types": ["vitest/globals", "node"]
22
+ }
28
23
  }
@@ -0,0 +1,7 @@
1
+ import { defineConfig } from 'vitest/config';
2
+ import tsconfigPaths from 'vite-tsconfig-paths';
3
+
4
+ export default defineConfig({
5
+ plugins: [tsconfigPaths()],
6
+ test: { globals: true, root: './', include: ['src/**/*.spec.ts'] },
7
+ });
@@ -2,41 +2,46 @@
2
2
  "schemaVersion": "1.0",
3
3
  "type": "boilerplate",
4
4
  "name": "02-saas-starter",
5
- "title": "SaaS Starter - Multi-Tenant Platform Boilerplate",
5
+ "title": "SaaS Starter - API multi-tenant com assinatura e faturamento",
6
6
  "path": "boilerplates/02-saas-starter",
7
7
  "readme": "boilerplates/02-saas-starter/README.md",
8
8
  "stack": [
9
- "NestJS",
10
- "Docker",
9
+ "NestJS 12",
10
+ "TypeORM",
11
+ "Postgres",
11
12
  "JWT",
12
- "Postgres"
13
+ "Vitest"
13
14
  ],
14
15
  "useCases": [
15
- "SaaS",
16
- "Admin",
17
- "Billing",
18
- "Auth"
16
+ "SaaS B2B",
17
+ "Multi-tenant",
18
+ "Assinatura",
19
+ "Faturamento",
20
+ "Auth com papéis"
19
21
  ],
20
22
  "commands": [
21
23
  "npm install",
22
24
  "npm run start:dev",
23
- "docker compose up -d",
24
- "npm test"
25
+ "npm test",
26
+ "npm run lint"
25
27
  ],
26
28
  "gates": [
27
- "npm run spec:check",
28
29
  "npm test",
29
- "npm run project:check"
30
+ "npm run lint",
31
+ "npm run build"
30
32
  ],
31
33
  "tokenPolicy": {
32
34
  "firstRead": [
33
35
  "boilerplate.manifest.json",
34
- "README.md"
36
+ "README.md",
37
+ "memory/30-domains/identity/context.md",
38
+ "memory/30-domains/billing/context.md"
35
39
  ],
36
40
  "avoidLoadingByDefault": [
37
41
  "node_modules",
38
42
  "dist",
39
43
  "coverage"
40
44
  ]
41
- }
45
+ },
46
+ "template": true
42
47
  }
@@ -1,34 +1,20 @@
1
- version: '3.8'
2
-
1
+ # Postgres para desenvolvimento: docker compose up -d db
3
2
  services:
4
- postgres:
5
- image: postgres:15-alpine
3
+ db:
4
+ image: postgres:17-alpine
6
5
  environment:
7
- POSTGRES_USER: ${DB_USER:-postgres}
8
- POSTGRES_PASSWORD: ${DB_PASSWORD:-postgres}
9
- POSTGRES_DB: ${DB_NAME:-saas_starter}
6
+ POSTGRES_USER: postgres
7
+ POSTGRES_PASSWORD: postgres
8
+ POSTGRES_DB: saas_starter
10
9
  ports:
11
10
  - "5432:5432"
12
11
  volumes:
13
- - postgres_data:/var/lib/postgresql/data
12
+ - db_data:/var/lib/postgresql/data
14
13
  healthcheck:
15
14
  test: ["CMD-SHELL", "pg_isready -U postgres"]
16
- interval: 10s
17
- timeout: 5s
18
- retries: 5
19
-
20
- redis:
21
- image: redis:7-alpine
22
- ports:
23
- - "6379:6379"
24
- volumes:
25
- - redis_data:/data
26
- healthcheck:
27
- test: ["CMD", "redis-cli", "ping"]
28
- interval: 10s
15
+ interval: 5s
29
16
  timeout: 5s
30
- retries: 5
17
+ retries: 10
31
18
 
32
19
  volumes:
33
- postgres_data:
34
- redis_data:
20
+ db_data: