forjajs 5.0.1 → 5.1.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 (164) hide show
  1. package/CHANGELOG.md +38 -2
  2. package/README.md +4 -2
  3. package/README.pt-BR.md +4 -1
  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/bin/init-project.js +1 -0
  50. package/dist/lib/core/journey.js +10 -0
  51. package/dist/lib/generators/memory-generator.d.ts +0 -11
  52. package/dist/lib/generators/memory-generator.js +5 -161
  53. package/dist/lib/generators/readme-generator.js +1 -1
  54. package/dist/lib/llm/json-output.d.ts +14 -0
  55. package/dist/lib/llm/json-output.js +77 -0
  56. package/dist/lib/project-wiring.d.ts +8 -0
  57. package/dist/lib/project-wiring.js +74 -2
  58. package/dist/lib/validators/structure-validator.js +0 -1
  59. package/dist/packages/llm/src/index.js +12 -2
  60. package/dist/scripts/llm-fit.js +23 -1
  61. package/docs/llm-fit-loop.md +16 -0
  62. package/memory/90-decisions/0088-templates-validados.md +3 -0
  63. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  64. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  65. package/package.json +1 -1
  66. package/specs/skills-do-projeto/plan.md +40 -0
  67. package/specs/skills-do-projeto/spec.md +63 -0
  68. package/specs/skills-do-projeto/tasks.md +27 -0
  69. package/templates/project/AGENTS.md +9 -0
  70. package/templates/project/agents/context-engineer.md +3 -0
  71. package/templates/project/agents/governance.md +3 -0
  72. package/templates/project/agents/marketing.md +3 -0
  73. package/templates/project/agents/orchestrator.md +3 -0
  74. package/templates/project/agents/product.md +3 -0
  75. package/templates/project/agents/sdd-architect.md +3 -0
  76. package/templates/project/skills/README.md +14 -0
  77. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  78. package/templates/project/skills/api-design/SKILL.md +77 -0
  79. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  80. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  81. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  82. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  83. package/templates/project/skills/commit-message/SKILL.md +143 -0
  84. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  85. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  86. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  87. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  88. package/templates/project/skills/event-storming/SKILL.md +95 -0
  89. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  90. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  91. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  92. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  93. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  94. package/templates/project/skills/observability/SKILL.md +93 -0
  95. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  96. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  97. package/templates/project/skills/pull-request/SKILL.md +101 -0
  98. package/templates/project/skills/query-performance/SKILL.md +83 -0
  99. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  100. package/templates/project/skills/release-notes/SKILL.md +87 -0
  101. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  102. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  103. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  104. package/templates/project/skills/testing/SKILL.md +109 -0
  105. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  106. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  107. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  108. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  109. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  110. package/templates/project/skills/web-performance/SKILL.md +72 -0
  111. package/boilerplates/02-saas-starter/.env.example +0 -25
  112. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  113. package/boilerplates/02-saas-starter/INFO.md +0 -252
  114. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  115. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  116. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  117. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  118. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  119. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  120. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  121. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  122. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  123. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  124. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  125. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  126. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  127. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  128. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  129. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  130. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  131. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  132. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  133. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  134. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  135. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  136. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  137. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  138. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  139. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  140. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  141. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  142. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  143. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  144. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  145. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  146. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  147. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  148. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  149. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  150. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  151. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  152. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  153. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  154. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  155. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  156. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  157. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  158. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  159. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  160. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  161. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  162. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  163. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  164. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
package/CHANGELOG.md CHANGED
@@ -13,11 +13,47 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
13
13
 
14
14
  ---
15
15
 
16
- ## [Unreleased]
16
+ ## [5.1.0] — 2026-10-21 — Skills, template de SaaS e mais agentes
17
17
 
18
18
  ### O que melhorou
19
19
 
20
- _(preencher a cada release: diff de produto vs. a versão anterior, antes das seções técnicas)_
20
+ - **O projeto passa a ter skills que as IAs realmente carregam.** São 34 skills em pt-BR (avaliar
21
+ produto, levantar e fatiar requisitos, event storming, modelagem de domínio, ADR, API, migrações,
22
+ arquitetura de front-end, acessibilidade, desempenho web, atualização de dependências, testes,
23
+ code review TypeScript, modelagem de ameaças, LGPD, observabilidade, release e git), instaladas em
24
+ `.claude/skills/` (Claude Code) e `.agents/skills/` (Codex). As 9 "skills" anteriores eram esboços
25
+ que nenhuma IA lia.
26
+ - **As skills falam a língua do Forja.** As que produzem artefatos dizem onde gravar: ADR em
27
+ `memory/90-decisions/`, requisitos em `specs/<slug>/spec.md`, entrega como handoff, postmortem com
28
+ `forja incident:record`. Cada sub-agent de papel lista as skills que deve usar.
29
+ - **Conferido como o resto da conexão:** `forja project:wire --check` valida as skills (frontmatter,
30
+ referências entre elas e comandos citados), e uma skill que você editar não é sobrescrita.
31
+ - **Novo template: `forja project:new minha-saas --template saas-starter`.** Uma API NestJS 12
32
+ multi-tenant que instala, compila e passa nos testes: cadastro que cria a organização, login e
33
+ refresh com papéis, planos com transições validadas e fatura mensal. O tenant vem sempre do token
34
+ (recurso de outro tenant responde 404), o preço vem da tabela de planos, nunca do cliente, e a API
35
+ não sobe sem os segredos configurados. O boilerplate antigo não compilava.
36
+ - **Mais agentes no `llm:run`: Gemini CLI, GitHub Copilot CLI, Cursor e opencode**, todos em modo
37
+ somente leitura (o Forja aplica as mudanças, não o provedor). Gemini e Cursor reportam uso de
38
+ tokens. O perfil `copilot` deixou de chamar o `gh copilot suggest`, que só sugeria comandos de
39
+ shell.
40
+
41
+ ### Adicionado
42
+
43
+ - `templates/project/skills/` (SPEC-051, ADR-0089); checks `skills-claude`/`skills-codex` no
44
+ `project:wire`; passo `skills` na jornada; `test/project-skills.test.js`.
45
+ - `boilerplates/02-saas-starter` como template validado (`"template": true`), na matriz
46
+ `project-smoke-full` do CI; ADR-0088 atualizado.
47
+ - Adapters `gemini-cli` (`--approval-mode plan -o json`), `copilot` (`copilot -s -p`), `cursor`
48
+ (`cursor-agent -p --mode plan --output-format json`) e `opencode` (`run --agent plan`), com
49
+ normalizadores em `lib/llm/json-output.ts`; `llm:doctor` exige as flags de somente leitura
50
+ (ADR-0090). `copilot`, `cursor` e `opencode` vêm desligados nos perfis padrão.
51
+
52
+ ### Removido
53
+
54
+ - Skills de esboço do gerador (`skills/` na raiz do projeto) e `scripts/lib/skill-loader.mjs`.
55
+ - Do `02-saas-starter`: o backend antigo (segredo JWT padrão, cobrança com valor do cliente,
56
+ `Math.random` simulando pagamento), Redis sem uso no `docker-compose.yml` e os guias desatualizados.
21
57
 
22
58
  ## [5.0.1] — 2026-10-10 — Correção: o upgrade nunca toca o código do projeto
23
59
 
package/README.md CHANGED
@@ -104,7 +104,7 @@ process followed?", the answer is a file, not a promise.
104
104
  re-wires older projects without touching the user's code — or the whole workspace with `--all`
105
105
  (ADR-0086). The NestJS backend follows the official NestJS 12 layout (ESM, Vitest, oxlint) and its
106
106
  `/api/ops` page shows the project's specs, open handoffs and indexed memory.
107
- - **Validated templates** — `project:new <name> --template clean-arch` starts from a boilerplate whose
107
+ - **Validated templates** — `project:new <name> --template clean-arch` (DDD) or `--template saas-starter` (multi-tenant SaaS with subscriptions and billing) starts from a boilerplate whose
108
108
  install, build, tests and lint are proven in CI; `project:templates` lists what is a template and
109
109
  what is reference architecture (ADR-0088).
110
110
  - **The user journey is a gate** — `npm test` and `release:check` run the whole journey (workspace →
@@ -112,7 +112,7 @@ process followed?", the answer is a file, not a promise.
112
112
  against the installed tarball, and fail if any command writes into the package itself.
113
113
  - **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
114
114
  (agent-team design), **ai-engineering** (knowledge base).
115
- - **LLM Fit Loop** — adapters de CLI, perfis no workspace, probes sem custo, observações e
115
+ - **LLM Fit Loop** — adapters de CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), perfis no workspace, probes sem custo, observações e
116
116
  recomendação determinística por papel/tarefa; credenciais nunca entram no Forja.
117
117
  - **Engineering Control Plane** (v3.0, ADR-0078) — the Engineering Graph turns ADRs/SPECs into
118
118
  first-class, queryable nodes; the Architecture Constitution checks real code against decisions
@@ -389,6 +389,8 @@ my-project/
389
389
  .claude/
390
390
  settings.json # hooks: forja hook:session-start / hook:user-prompt
391
391
  agents/ # orchestrator, product, sdd-architect, context-engineer, governance, marketing
392
+ skills/ # 34 skills (requirements, domain modeling, ADR, front-end, a11y, testing, TS code review, LGPD…)
393
+ .agents/skills/ # the same skills for Codex
392
394
  .mcp.json # forja MCP server (+ codegraph when installed)
393
395
  .codex/config.toml # forja MCP for Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
394
396
  .forja/models.json # AI fallback chain (engine switch)
package/README.pt-BR.md CHANGED
@@ -86,7 +86,8 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
86
86
  - **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
87
87
  - **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
88
88
  - **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto e anexam a spec citada no prompt, seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
89
- - **Templates validados** — `project:new <nome> --template clean-arch` parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
89
+ - **Templates validados** — `project:new <nome> --template clean-arch` (DDD) ou `--template saas-starter` (SaaS multi-tenant com assinatura e faturamento) parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
90
+ - **LLM Fit Loop** — `llm:run` executa tarefas supervisionadas por CLI (Codex, Claude; Gemini, Copilot CLI, Cursor e opencode em modo somente leitura), com perfis no workspace, probes sem custo, observações e recomendação por papel/tarefa; credenciais nunca entram no Forja (ADR-0090).
90
91
  - **A jornada do usuário é gate** — `npm test` e `release:check` percorrem a jornada inteira (workspace → projeto → memória, contexto, specs, hooks, MCP e handoffs dentro do projeto), contra o fonte e contra o pacote instalado, e reprovam se algum comando escrever dentro do pacote.
91
92
  - **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
92
93
  - **Engineering Control Plane** (v3.0, ADR-0078) — o Engineering Graph vira ADRs/SPECs em nós de primeira classe consultáveis; a Architecture Constitution checa o código real contra decisões já registradas; o Change Risk Engine pontua uma mudança 0-100 com fatores nomeados e evidenciados; `forja simulate` testa um ref num worktree isolado e nunca promove sozinho. Uma façade só, `forja engineer "<objetivo>"`, compõe tudo isso — contexto, ADRs relevantes, checagem de arquitetura, risco, agentes recomendados, incidentes parecidos — antes de você começar. Todo score é informação pra um humano/regra de política consultar, nunca uma decisão autônoma por si só.
@@ -307,6 +308,8 @@ meu-projeto/
307
308
  .claude/
308
309
  settings.json # hooks: forja hook:session-start / hook:user-prompt
309
310
  agents/ # orchestrator, product, sdd-architect, context-engineer, governance, marketing
311
+ skills/ # 34 skills (requisitos, modelagem de domínio, ADR, front-end, acessibilidade, testes, code review TS, LGPD…)
312
+ .agents/skills/ # as mesmas skills para o Codex
310
313
  .mcp.json # servidor MCP do forja (+ codegraph quando instalado)
311
314
  .codex/config.toml # MCP do forja no Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
312
315
  .forja/models.json # cadeia de fallback entre IAs (troca de motor)
@@ -1,305 +1,70 @@
1
- # SaaS Starter - Multi-Tenant Platform Boilerplate
1
+ # 02 — SaaS Starter multi-tenant
2
2
 
3
- **Production-ready NestJS + PostgreSQL + Redis** scaffold for launching SaaS in weeks, not months.
3
+ API NestJS 12 (ESM) para um SaaS B2B: **cada organização é um tenant**, com cadastro, login, papéis
4
+ e assinatura com faturamento mensal. O ponto de partida já vem com as decisões de segurança que
5
+ costumam ficar para depois — e com testes que as cobram.
4
6
 
5
- ## Features
7
+ ## O que vem pronto
6
8
 
7
- ✅ **Multi-Tenant Architecture** — Secure data isolation, tenant-per-database-row pattern
8
- ✅ **Authentication** — JWT-based with refresh tokens, local + passport strategies
9
- ✅ **RBAC** — Owner, Admin, Member roles with permission matrix
10
- ✅ **Subscription Management** — Free, Pro, Enterprise plans with smart transitions
11
- ✅ **Billing** — Mock Stripe payment gateway with invoices & transactions
12
- ✅ **Type-Safe** — 100% TypeScript, strict mode, no `any`
13
- ✅ **Well-Documented** — 10-level memory structure, API specs, patterns
14
- ✅ **Agent-Ready** — Designed for multi-agent orchestration
15
- ✅ **Docker-Compose** — Local development in 1 command
16
- ✅ **E2E Tests** — Happy-path scenarios for critical flows
9
+ | Contexto | Faz | Garantias |
10
+ |---|---|---|
11
+ | `identity` | Cadastro (cria organização + dona), login, refresh, `me`, membros | Senha com scrypt e comparação em tempo constante; access (15 min) e refresh (7 dias) com segredos distintos e `typ` checado; login sem revelar se o e-mail existe |
12
+ | `billing` | Planos, assinatura, mudança de plano, fatura do mês | Preço vem da tabela de planos (nunca do cliente), em centavos inteiros; transições de plano validadas no domínio; uma fatura por tenant e período (idempotente) |
13
+ | `platform` | Configuração, JWT, papéis | A API não sobe sem `DATABASE_URL`, `JWT_SECRET` e `JWT_REFRESH_SECRET` (nada de segredo padrão); `RolesGuard` por rota |
17
14
 
18
- ## Quick Start
15
+ O **tenant vem sempre do token**, nunca do corpo ou da URL: toda consulta filtra por `tenantId`, e
16
+ um recurso de outro tenant responde 404. O `ValidationPipe` rejeita campos fora do DTO (sem
17
+ atribuição em massa de `roles`, `tenantId`, `amount`).
19
18
 
20
- ```bash
21
- # 1. Enter directory
22
- cd boilerplates/02-saas-starter
23
-
24
- # 2. Install dependencies
25
- npm install
26
-
27
- # 3. Start database & cache
28
- docker-compose up -d
19
+ ## Estrutura
29
20
 
30
- # 4. Configure environment
31
- cp .env.example .env.local
32
-
33
- # 5. Run server
34
- npm run start:dev
35
-
36
- # 6. Open API docs
37
- # http://localhost:3000/api/docs
38
21
  ```
39
-
40
- **That's it!** Server running on `localhost:3000`.
41
-
42
- ## API Examples
43
-
44
- ### Signup (Create Org + User)
45
-
46
- ```bash
47
- curl -X POST http://localhost:3000/api/auth/signup \
48
- -H "Content-Type: application/json" \
49
- -d '{
50
- "email": "founder@example.com",
51
- "password": "SecureP@ss123",
52
- "organizationName": "My SaaS"
53
- }'
22
+ backend/src/
23
+ platform/ # config validada, TokenService, JwtAuthGuard, RolesGuard
24
+ identity/
25
+ domain/ # Organization, User, porta IdentityRepository, hash de senha
26
+ application/ # AuthService (casos de uso)
27
+ adapters/http|persistence
28
+ billing/
29
+ domain/ # planos e transições, agregado Subscription, porta BillingRepository
30
+ application/ # BillingService
31
+ adapters/http|persistence
32
+ memory/30-domains/ # contexto de cada domínio na linguagem ubíqua (leia antes do código)
54
33
  ```
55
34
 
56
- ### Login
35
+ Mesma regra de dependência do template `clean-arch`: domínio sem Nest nem ORM, adapters implementam
36
+ as portas, ligação no módulo.
57
37
 
58
- ```bash
59
- curl -X POST http://localhost:3000/api/auth/login-email \
60
- -H "Content-Type: application/json" \
61
- -d '{ "email": "founder@example.com", "password": "SecureP@ss123" }'
62
- ```
63
-
64
- ### Get Current User
65
-
66
- ```bash
67
- curl -X GET http://localhost:3000/api/auth/me \
68
- -H "Authorization: Bearer {accessToken}"
69
- ```
70
-
71
- ### Upgrade Subscription
38
+ ## Rodando
72
39
 
73
40
  ```bash
74
- curl -X POST http://localhost:3000/api/subscriptions/{id}/upgrade \
75
- -H "Authorization: Bearer {accessToken}" \
76
- -H "Content-Type: application/json" \
77
- -d '{ "newPlan": "pro" }'
78
- ```
79
-
80
- ### Process Payment (Mock)
81
-
82
- ```bash
83
- curl -X POST http://localhost:3000/api/billing/charge \
84
- -H "Authorization: Bearer {accessToken}" \
85
- -H "Content-Type: application/json" \
86
- -d '{ "amount": 99.00, "description": "Pro Plan" }'
87
- ```
88
-
89
- See [QUICK_START.md](./QUICK_START.md) for more examples.
90
-
91
- ## Architecture
92
-
93
- ```
94
- ┌─────────────────────────┐
95
- │ NestJS Controllers │ (HTTP endpoints)
96
- ├─────────────────────────┤
97
- │ Services │ (Business logic)
98
- ├─────────────────────────┤
99
- │ Repositories │ (Data access)
100
- ├─────────────────────────┤
101
- │ PostgreSQL + Redis │ (Persistence)
102
- └─────────────────────────┘
103
- ```
104
-
105
- **Multi-Tenant**: Every table has `tenantId` column. All queries filtered by tenant.
106
- **RBAC**: Roles stored in User entity, checked via RolesGuard decorator.
107
- **JWT**: Stateless auth, 15min access token, 7day refresh token.
108
-
109
- ## Project Structure
110
-
111
- ```
112
- backend/
113
- ├── src/
114
- │ ├── modules/
115
- │ │ ├── auth/ (JWT, login, signup)
116
- │ │ ├── users/ (RBAC, user management)
117
- │ │ ├── organizations/(Multi-tenant)
118
- │ │ ├── subscriptions/(Plans, upgrades)
119
- │ │ └── billing/ (Invoices, payments mock)
120
- │ ├── common/
121
- │ │ ├── decorators/ (Roles, TenantId)
122
- │ │ ├── middleware/ (Guards, logging)
123
- │ │ └── filters/ (Error handling)
124
- │ ├── config/ (Database, JWT)
125
- │ ├── app.module.ts
126
- │ └── main.ts
127
- ├── test/ (E2E tests)
128
- ├── package.json
129
- └── tsconfig.json
130
-
131
- memory/ (Documentation)
132
- ├── 00-global/ (Mission, patterns, policies)
133
- ├── 10-product/ (Vision, personas, rules)
134
- ├── 20-architecture/ (Tech decisions, diagrams)
135
- ├── 30-domains/ (Auth, subscriptions, billing)
136
- ├── 40-delivery/ (Roadmap, sprints, backlog)
137
- ├── 50-orchestration/ (Agent topology, handoffs)
138
- ├── 60-runs/ (Execution logs)
139
- ├── 70-summaries/ (Executive summaries)
140
- ├── 80-data/ (Database schema)
141
- └── 90-decisions/ (ADRs)
142
-
143
- docker-compose.yml (PostgreSQL + Redis)
144
- .env.example (Configuration template)
145
- QUICK_START.md (5-minute setup guide)
146
- ```
147
-
148
- ## Database Schema
149
-
150
- **Entities**:
151
- - `User` — Email, roles, tenant isolation
152
- - `Organization` — Plan, tenant ID, owner
153
- - `Subscription` — Current plan, billing period
154
- - `Invoice` — Charges, payment status
155
- - `AuditLog` — User actions, compliance
156
-
157
- See [memory/80-data/schema.md](./memory/80-data/schema.md).
158
-
159
- ## Authentication Flow
160
-
161
- 1. **Signup**: User + Org created, JWT tokens returned
162
- 2. **Login**: Email + password validated, tokens returned
163
- 3. **Protected routes**: JWT header validated, tenant extracted
164
- 4. **Logout**: Token cached in Redis for blacklist (future)
165
-
166
- Strategies:
167
- - **Local**: Username/password (Passport Local)
168
- - **JWT**: Bearer token (Passport JWT)
169
-
170
- ## Subscription Plans
171
-
172
- | Plan | Price | API Calls | Storage | Users |
173
- |------|-------|-----------|---------|-------|
174
- | Free | $0 | 1k/mo | 1GB | 1 |
175
- | Pro | $99 | 100k/mo | 100GB | 5 (+$10 each) |
176
- | Enterprise | Custom | ∞ | ∞ | ∞ |
177
-
178
- Upgrade instantly, downgrade at period end. Pro-rata billing for mid-cycle changes.
179
-
180
- ## Payment (Mock)
181
-
182
- 90% success rate, 10% failure (for testing). Real Stripe integration in Q2.
183
-
184
- ```typescript
185
- POST /api/billing/charge
186
- {
187
- "amount": 99.00,
188
- "description": "Pro Plan Upgrade"
189
- }
190
- ```
191
-
192
- Returns invoice with mock transaction ID.
193
-
194
- ## Development
195
-
196
- ```bash
197
- # Format + Lint
198
- npm run format && npm run lint
199
-
200
- # Tests
201
- npm run test # Unit
202
- npm run test:cov # Coverage
203
- npm run test:e2e # E2E
204
-
205
- # Build
206
- npm run build
207
- npm run start:prod
208
- ```
209
-
210
- ## Environment Variables
211
-
212
- ```env
213
- NODE_ENV=development
214
- PORT=3000
215
- DB_HOST=localhost
216
- DB_PORT=5432
217
- DB_USER=postgres
218
- DB_PASSWORD=postgres
219
- DB_NAME=saas_starter
220
- JWT_SECRET=dev-secret-key
221
- JWT_REFRESH_SECRET=dev-refresh-secret
222
- ```
223
-
224
- See [.env.example](./.env.example) for all options.
225
-
226
- ## Documentation
227
-
228
- - **Quick Start**: [QUICK_START.md](./QUICK_START.md)
229
- - **API Reference**: [memory/30-domains/](./memory/30-domains/)
230
- - **Architecture**: [memory/20-architecture/overview.md](./memory/20-architecture/overview.md)
231
- - **Patterns & Conventions**: [memory/00-global/patterns.md](./memory/00-global/patterns.md)
232
- - **Business Rules**: [memory/10-product/business-rules.md](./memory/10-product/business-rules.md)
233
- - **Database Schema**: [memory/80-data/schema.md](./memory/80-data/schema.md)
234
-
235
- **Navigation**: See [memory/00-global/index.md](./memory/00-global/index.md) for full index.
236
-
237
- ## Roadmap
238
-
239
- **Q1 2024** (Current): MVP with auth, subscriptions, billing mock ✅
240
- **Q2 2024**: Real Stripe, webhooks, analytics
241
- **Q3 2024**: Observability, compliance, performance
242
- **Q4 2024**: Multi-currency, internationalization
243
-
244
- See [memory/40-delivery/roadmap.md](./memory/40-delivery/roadmap.md).
245
-
246
- ## Extending
247
-
248
- ### Add a New Endpoint
249
-
250
- 1. Create DTO in `modules/{domain}/dto/`
251
- 2. Add method in `modules/{domain}/{domain}.service.ts`
252
- 3. Add route in `modules/{domain}/{domain}.controller.ts`
253
- 4. Add tests in `test/{domain}.e2e-spec.ts`
254
- 5. Document in `memory/30-domains/{domain}/api.md`
255
-
256
- See [memory/00-global/patterns.md](./memory/00-global/patterns.md).
257
-
258
- ### Add a New Module
259
-
260
- 1. Create folder in `modules/`
261
- 2. Create `{module}.service.ts`, `{module}.controller.ts`, `{module}.module.ts`
262
- 3. Add module to `app.module.ts` imports
263
- 4. Create `entity.ts` and register in database config
264
- 5. Document in `memory/30-domains/{module}/`
265
-
266
- ## Security
267
-
268
- - **Passwords**: Bcrypt cost=12
269
- - **JWT**: HS256, secrets in env
270
- - **Tenant Isolation**: Row-level filtering by tenantId
271
- - **SQL Injection**: TypeORM parameterized queries
272
- - **RBAC**: Roles decorator on controllers
273
- - **PII**: No passwords/tokens in logs
274
-
275
- See [memory/10-product/nfrs.md](./memory/10-product/nfrs.md) for security requirements.
276
-
277
- ## Troubleshooting
278
-
279
- **Port 3000 in use?**
280
- ```bash
281
- lsof -i :3000 && kill -9 {PID}
282
- ```
283
-
284
- **Database connection failed?**
285
- ```bash
286
- docker-compose ps
287
- docker-compose logs postgres
288
- ```
289
-
290
- **Module not found?**
291
- ```bash
292
- rm -rf node_modules && npm install
293
- ```
294
-
295
- ## License
296
-
297
- MIT
298
-
299
- ## Contributing
300
-
301
- Patches welcome! See [memory/00-global/agent-contract.md](./memory/00-global/agent-contract.md) for agent onboarding.
302
-
303
- ---
304
-
305
- **Ready to build?** See [QUICK_START.md](./QUICK_START.md) →
41
+ forja project:new minha-saas --template saas-starter
42
+ cd ~/forja-workspace/projects/minha-saas
43
+ docker compose up -d db # Postgres de desenvolvimento
44
+ cd backend && cp .env.example .env # preencha JWT_SECRET e JWT_REFRESH_SECRET (openssl rand -base64 48)
45
+ npm run start:dev # http://localhost:3000/api — Swagger em /api/docs fora de produção
46
+ npm test # Vitest: domínio e casos de uso, sem Postgres
47
+ npm run lint # oxlint com checagem de tipos
48
+ ```
49
+
50
+ `synchronize` do TypeORM fica ligado só fora de produção. Antes do primeiro deploy, troque por
51
+ migrações (`typeorm migration:generate`).
52
+
53
+ ## Rotas
54
+
55
+ | Método | Rota | Papel |
56
+ |---|---|---|
57
+ | POST | `/api/auth/signup` · `/api/auth/login` · `/api/auth/refresh` | público |
58
+ | GET | `/api/me` · `/api/organization` | autenticado |
59
+ | GET | `/api/users` | owner, admin |
60
+ | GET | `/api/billing/plans` · `/api/billing/subscription` · `/api/billing/invoices` · `/api/billing/invoices/:id` | autenticado (faturas: owner, admin) |
61
+ | PUT | `/api/billing/subscription/plan` | owner |
62
+ | POST | `/api/billing/invoices/current` | owner, admin |
63
+
64
+ ## O que fica com você
65
+
66
+ - **Gateway de pagamento**: a fatura nasce `open`; integrar Stripe/Pagar.me/Asaas é um adapter novo
67
+ que marca `paid` por webhook (verifique a assinatura do webhook).
68
+ - **Convites de membros**, recuperação de senha e verificação de e-mail.
69
+ - **Revogação de refresh token** (lista de sessões) se precisar de logout em todos os aparelhos.
70
+ - **Rate limit** no login (`@nestjs/throttler`).
@@ -0,0 +1,13 @@
1
+ # Copie para .env (nesta pasta) e preencha. Sem JWT_SECRET/JWT_REFRESH_SECRET/DATABASE_URL a API não sobe.
2
+ NODE_ENV=development
3
+ PORT=3000
4
+
5
+ # PostgreSQL (docker compose up -d db)
6
+ DATABASE_URL=postgres://postgres:postgres@localhost:5432/saas_starter
7
+
8
+ # Segredos distintos, longos e aleatórios (ex.: openssl rand -base64 48)
9
+ JWT_SECRET=
10
+ JWT_REFRESH_SECRET=
11
+
12
+ # Moeda das faturas (ISO 4217)
13
+ BILLING_CURRENCY=BRL
@@ -0,0 +1,8 @@
1
+ {
2
+ "$schema": "./node_modules/oxlint/configuration_schema.json",
3
+ "rules": {
4
+ "typescript/no-explicit-any": "error",
5
+ "typescript/no-floating-promises": "error"
6
+ },
7
+ "env": { "node": true }
8
+ }
@@ -0,0 +1,6 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/nest-cli",
3
+ "collection": "@nestjs/schematics",
4
+ "sourceRoot": "src",
5
+ "compilerOptions": { "deleteOutDir": true }
6
+ }
@@ -1,87 +1,46 @@
1
1
  {
2
- "name": "@saas-starter/backend",
3
- "version": "1.0.0",
4
- "description": "SaaS Starter NestJS Backend",
5
- "author": "SaaS Starter",
2
+ "name": "saas-starter-api",
3
+ "version": "0.1.0",
6
4
  "private": true,
7
- "license": "MIT",
5
+ "type": "module",
8
6
  "scripts": {
9
- "prebuild": "rimraf dist",
10
7
  "build": "nest build",
11
- "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
12
8
  "start": "nest start",
13
9
  "start:dev": "nest start --watch",
14
- "start:debug": "nest start --debug --watch",
15
10
  "start:prod": "node dist/main",
16
- "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
17
- "test": "jest",
18
- "test:watch": "jest --watch",
19
- "test:cov": "jest --coverage",
20
- "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
21
- "test:e2e": "jest --config ./test/jest-e2e.json",
22
- "typeorm": "typeorm-ts-node-esm",
23
- "migration:create": "typeorm-ts-node-esm migration:create ./src/migrations",
24
- "migration:run": "typeorm-ts-node-esm migration:run -d ./src/config/database.ts",
25
- "migration:revert": "typeorm-ts-node-esm migration:revert -d ./src/config/database.ts",
26
- "seed": "ts-node src/scripts/seed.ts"
11
+ "format": "prettier --write \"src/**/*.ts\"",
12
+ "lint": "oxlint --type-aware src/",
13
+ "test": "vitest run",
14
+ "test:watch": "vitest",
15
+ "test:cov": "vitest run --coverage"
27
16
  },
28
17
  "dependencies": {
29
- "@nestjs/common": "^10.0.0",
30
- "@nestjs/config": "^3.0.0",
31
- "@nestjs/core": "^10.0.0",
32
- "@nestjs/jwt": "^11.0.0",
33
- "@nestjs/passport": "^10.0.0",
34
- "@nestjs/platform-express": "^10.0.0",
35
- "@nestjs/swagger": "^7.1.0",
36
- "@nestjs/typeorm": "^9.0.0",
37
- "bcrypt": "^5.1.1",
18
+ "@nestjs/common": "^12.1.2",
19
+ "@nestjs/config": "^12.0.1",
20
+ "@nestjs/core": "^12.1.2",
21
+ "@nestjs/jwt": "^12.0.3",
22
+ "@nestjs/platform-express": "^12.1.2",
23
+ "@nestjs/swagger": "^12.0.2",
24
+ "@nestjs/typeorm": "^12.0.2",
38
25
  "class-transformer": "^0.5.1",
39
- "class-validator": "^0.14.0",
40
- "pg": "^8.11.0",
41
- "passport": "^0.7.0",
42
- "passport-jwt": "^4.0.1",
43
- "passport-local": "^1.0.0",
44
- "redis": "^4.6.0",
45
- "reflect-metadata": "^0.1.13",
46
- "rxjs": "^7.8.1",
47
- "swagger-ui-express": "^5.0.0",
48
- "typeorm": "^0.3.17",
49
- "uuid": "^9.0.1"
26
+ "class-validator": "^0.15.1",
27
+ "pg": "^8.23.1",
28
+ "reflect-metadata": "^0.2.2",
29
+ "rxjs": "^7.8.2",
30
+ "typeorm": "^1.1.2"
50
31
  },
51
32
  "devDependencies": {
52
- "@nestjs/cli": "^10.0.0",
53
- "@nestjs/schematics": "^10.0.0",
54
- "@nestjs/testing": "^10.0.0",
55
- "@types/bcrypt": "^5.0.2",
56
- "@types/express": "^4.17.17",
57
- "@types/jest": "^29.5.2",
58
- "@types/node": "^20.3.1",
59
- "@types/passport-jwt": "^3.0.13",
60
- "@types/passport-local": "^1.0.38",
61
- "@types/supertest": "^2.0.12",
62
- "@typescript-eslint/eslint-plugin": "^5.59.11",
63
- "@typescript-eslint/parser": "^5.59.11",
64
- "eslint": "^8.42.0",
65
- "jest": "^29.5.0",
66
- "prettier": "^2.8.8",
67
- "rimraf": "^5.0.1",
68
- "supertest": "^6.3.3",
69
- "ts-jest": "^29.1.0",
70
- "ts-loader": "^9.4.3",
71
- "ts-node": "^10.9.1",
72
- "tsconfig-paths": "^4.2.0",
73
- "typeorm-ts-node-esm": "^10.0.0",
74
- "typescript": "^5.1.3"
75
- },
76
- "jest": {
77
- "moduleFileExtensions": ["js", "json", "ts"],
78
- "rootDir": "src",
79
- "testRegex": ".*\\.spec\\.ts$",
80
- "transform": {
81
- "^.+\\.(t|j)s$": "ts-jest"
82
- },
83
- "collectCoverageFrom": ["**/*.(t|j)s"],
84
- "coverageDirectory": "../coverage",
85
- "testEnvironment": "node"
33
+ "@nestjs/cli": "^12.0.8",
34
+ "@nestjs/schematics": "^12.0.6",
35
+ "@nestjs/testing": "^12.1.2",
36
+ "@types/express": "^5.0.6",
37
+ "@types/node": "^26.6.4",
38
+ "@vitest/coverage-v8": "^5.0.3",
39
+ "oxlint": "^1.87.0",
40
+ "oxlint-tsgolint": "^7.0.2003",
41
+ "prettier": "^3.9.9",
42
+ "typescript": "^6.0.3",
43
+ "vite-tsconfig-paths": "^6.1.1",
44
+ "vitest": "^5.0.3"
86
45
  }
87
46
  }