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,72 @@
1
+ ---
2
+ name: web-performance
3
+ description: Use quando uma aplicação web está lenta ou precisa cumprir metas de Core Web Vitals: separa dados de campo e de laboratório, diagnostica LCP, INP e CLS, revisa bundle, imagens, fontes e cache, e propõe correções ordenadas pelo efeito esperado, com verificação antes e depois.
4
+ ---
5
+
6
+ # Desempenho Web
7
+
8
+ O que importa é o que os usuários reais experimentam, no aparelho e na rede deles. Uma nota 100 no Lighthouse da sua máquina não diz nada sobre um celular intermediário em 4G. Meça no campo, diagnostique no laboratório, corrija o que a medição apontar.
9
+
10
+ A saída padrão é um **diagnóstico e correções ordenadas**. Altere código só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Metas: os limites "bons" das Core Web Vitals no percentil 75 dos usuários: **LCP ≤ 2,5 s**, **INP ≤ 200 ms**, **CLS ≤ 0,1**. Metas do projeto vêm de `requirements-gathering` (`RNF-NN`).
15
+ - Entradas: dados de campo (CrUX, o RUM do projeto, a biblioteca `web-vitals`), dados de laboratório (Lighthouse, DevTools Performance, WebPageTest), o build e o framework.
16
+ - Não otimize sem medição. Cada correção nomeia a métrica que melhora.
17
+
18
+ ## Meça
19
+
20
+ 1. **Campo primeiro**: o percentil 75 por página e por tipo de aparelho. Sem dados de campo, instrumente com `web-vitals` e mande para o backend de métricas (`observability`).
21
+ 2. **Laboratório** para encontrar a causa: Lighthouse e o painel Performance do DevTools com limitação de CPU (4×) e rede (4G lento), num build de produção.
22
+ 3. **Bundle**: o analisador do bundler (`next build` mostra o tamanho por rota; `vite-bundle-visualizer`, `source-map-explorer`).
23
+
24
+ ## Diagnostique
25
+
26
+ | Métrica | Causas comuns | Correções típicas |
27
+ |---|---|---|
28
+ | **LCP** (maior conteúdo visível) | Servidor lento (TTFB), imagem principal grande ou carregada tarde, CSS/JS bloqueando a renderização, conteúdo renderizado só no cliente | Cache/CDN e renderização no servidor, `fetchpriority="high"` e dimensões certas na imagem LCP, formatos modernos (AVIF/WebP), CSS crítico, remover JS que bloqueia |
29
+ | **INP** (resposta à interação) | Tarefas longas no thread principal, hidratação pesada, handlers que fazem trabalho demais, re-renderizações em cascata | Dividir tarefas longas, adiar o que não é urgente, mover trabalho para Web Workers, reduzir JS do cliente (Server Components), memoização onde a medição mostra re-renderização cara |
30
+ | **CLS** (estabilidade visual) | Imagens e iframes sem dimensões, anúncios/embeds injetados, fontes que trocam e mudam o tamanho, conteúdo inserido acima do existente | `width`/`height` ou `aspect-ratio`, espaço reservado, `font-display` com fallback de métricas ajustadas, inserir conteúdo abaixo da dobra ou em resposta a uma interação |
31
+
32
+ **Também verifique**
33
+ - **JavaScript**: o tamanho por rota, divisão de código por rota e por interação (`import()` dinâmico), dependências grandes trocáveis, polyfills desnecessários.
34
+ - **Imagens**: tamanhos responsivos (`srcset`/`sizes` ou o componente de imagem do framework), lazy loading abaixo da dobra e nunca na imagem LCP.
35
+ - **Fontes**: poucas famílias e pesos, `woff2`, pré-carregamento só da fonte usada acima da dobra.
36
+ - **Cache**: arquivos com hash e `Cache-Control: immutable`; HTML com revalidação; compressão Brotli.
37
+ - **Terceiros**: cada script de terceiro (analytics, chat, anúncios) tem um custo medido e é carregado depois do conteúdo.
38
+ - **Dados**: cascatas de requisições (uma depende da outra), respostas grandes demais, ausência de paginação (`api-design`).
39
+
40
+ ## Verifique
41
+
42
+ Repita a mesma medição de laboratório depois da mudança, no mesmo perfil, e compare. Confirme no campo depois do deploy (a janela do CrUX é de 28 dias; o RUM próprio mostra antes). Defina um orçamento de desempenho no CI (tamanho de bundle por rota, Lighthouse CI) para não regredir.
43
+
44
+ ## Formato
45
+
46
+ ```
47
+ ## Medição
48
+ | Página | Aparelho | LCP p75 | INP p75 | CLS p75 | Fonte (campo/lab) |
49
+
50
+ ## Diagnóstico
51
+ | Métrica | Causa | Evidência (trace, waterfall, bundle) |
52
+
53
+ ## Correções (ordenadas por efeito esperado / custo)
54
+ | # | Correção | Métrica | Efeito esperado | Custo |
55
+
56
+ ## Verificação e orçamento
57
+ <antes → depois; orçamento proposto para o CI>
58
+ ```
59
+
60
+ ## Próximo
61
+
62
+ - `frontend-architecture` quando a causa é estrutural (estado global, `'use client'` demais).
63
+ - `observability`: Core Web Vitals de campo como SLIs.
64
+ - `ci-pipeline-review` para o orçamento de desempenho no CI.
65
+
66
+ ## Evite
67
+
68
+ - Otimizar pela nota do Lighthouse em vez das métricas de campo.
69
+ - Medir em modo de desenvolvimento ou numa máquina potente sem limitação.
70
+ - Lazy loading na imagem do LCP.
71
+ - Memoizar tudo "por precaução".
72
+ - Afirmar uma melhora sem números de antes e depois.
@@ -1,25 +0,0 @@
1
- # Environment Variables for SaaS Starter
2
-
3
- ## Server
4
- NODE_ENV=development
5
- PORT=3000
6
-
7
- ## Database
8
- DB_HOST=localhost
9
- DB_PORT=5432
10
- DB_USER=postgres
11
- DB_PASSWORD=postgres
12
- DB_NAME=saas_starter
13
- DB_LOGGING=false
14
-
15
- ## JWT
16
- JWT_SECRET=your-secret-key-here-change-in-production
17
- JWT_REFRESH_SECRET=your-refresh-secret-key-here-change-in-production
18
-
19
- ## Redis
20
- REDIS_HOST=localhost
21
- REDIS_PORT=6379
22
-
23
- ## Stripe (Future)
24
- STRIPE_API_KEY=sk_test_your_key_here
25
- STRIPE_WEBHOOK_SECRET=whsec_your_secret_here
@@ -1,190 +0,0 @@
1
- # SaaS Starter - Checklist de Criação ✅
2
-
3
- Data: 2024-01-15
4
- Status: **COMPLETO** 🚀
5
-
6
- ## Memory Structure (10 Níveis) ✅
7
-
8
- ### 00-Global (Políticas & Princípios)
9
- - ✅ mission.md — Visão, objetivos, papéis de agentes
10
- - ✅ patterns.md — Code patterns, conventions, testing
11
- - ✅ context-policy.md — Gestão de níveis, freshness, limpeza
12
- - ✅ agent-contract.md — Ciclo de vida, responsabilidades, handoffs
13
- - ✅ index.md — Índice completo com navegação
14
-
15
- ### 10-Product (Visão & Regras)
16
- - ✅ vision.md — Proposição de valor, diferencial, 12-month vision
17
- - ✅ personas.md — Buyer personas, user journeys, feature prioritization
18
- - ✅ business-rules.md — Planos, billing, RBAC, compliance, cancellation
19
- - ✅ nfrs.md — Performance, scalability, security, compliance requirements
20
-
21
- ### 20-Architecture (Decisões Técnicas)
22
- - ✅ overview.md — Diagrama, stack, fluxos, padrões, fases
23
-
24
- ### 30-Domains (Domínios de Negócio)
25
- - ✅ auth/context.md — O que é auth, fluxos, regras, status
26
- - ✅ auth/api.md — 5 endpoints (signup, login, refresh, logout, me) + examples
27
- - ✅ subscriptions/context.md — Planos, fluxos, regras, métricas
28
- - ✅ subscriptions/api.md — 5 endpoints (get, create, upgrade, cancel, usage)
29
- - ✅ billing/context.md — Pagamentos, gateway mock, invoices, regras
30
- - ✅ billing/api.md — 8 endpoints (charge, invoices, refunds, payment methods)
31
-
32
- ### 40-Delivery (Roadmap & Sprints)
33
- - ✅ roadmap.md — 12 meses, Q1-Q4 goals, risks, metrics
34
- - ✅ sprint-atual.md — Sprint 1 tasks, blockers, velocity
35
- - ✅ backlog.md — P0-P3 itens, dependencies, capacity planning
36
-
37
- ### 50-Orchestration (Topologia de Agents)
38
- - ✅ topology.md — Sequência, parallelização, timeline, success criteria
39
- - ✅ handoffs/ — Diretório preparado para handoff documents
40
-
41
- ### 60-Runs (Logs de Execução)
42
- - ✅ index.md — Índice com template de run document
43
-
44
- ### 70-Summaries (Sínteses Executivas)
45
- - ✅ global.md — Status geral, funcionalidades, metrics, bloqueadores
46
-
47
- ### 80-Data (Schemas & Migrations)
48
- - ✅ schema.md — 7 entidades (User, Org, Subscription, Invoice, Transaction, AuditLog, APIKey)
49
- - ✅ Relacionamentos, constraints, indexes documentados
50
-
51
- ### 90-Decisions (ADRs)
52
- - ✅ adr-template.md — Template + exemplo (PostgreSQL choice)
53
-
54
- ## Backend NestJS ✅
55
-
56
- ### Entities (5 criadas)
57
- - ✅ User — Email, roles, tenant isolation
58
- - ✅ Organization — Plan, tenantId, owner
59
- - ✅ Subscription — Plan, status, billing period
60
- - ✅ Invoice — Charges, payment status, items
61
- - ✅ Imports no database.ts
62
-
63
- ### Modules (5 completos)
64
-
65
- #### Auth Module
66
- - ✅ auth.service.ts — Signup, login, validateUser, token generation
67
- - ✅ auth.controller.ts — 5 endpoints (signup, login, refresh, logout, me)
68
- - ✅ jwt.strategy.ts — JWT validation
69
- - ✅ local.strategy.ts — Email/password validation
70
- - ✅ auth.dto.ts — SignupDto, LoginDto, RefreshTokenDto
71
- - ✅ auth.module.ts — Module definition com imports
72
-
73
- #### Organizations Module
74
- - ✅ organizations.service.ts — findByTenantId, create, updatePlan
75
- - ✅ organizations.controller.ts — GET /organizations
76
- - ✅ organizations.module.ts — Module definition
77
- - ✅ organization.entity.ts — Entity com indexes
78
-
79
- #### Users Module
80
- - ✅ users.service.ts — findById, findByEmail, create, updateRoles, list
81
- - ✅ users.controller.ts — GET /users
82
- - ✅ users.module.ts — Module definition
83
- - ✅ user.entity.ts — Entity com RBAC roles
84
-
85
- #### Subscriptions Module
86
- - ✅ subscriptions.service.ts — getOrCreate, upgrade, getUsage (planos + validação)
87
- - ✅ subscriptions.controller.ts — GET, POST /subscriptions/{id}/upgrade, usage
88
- - ✅ subscriptions.module.ts — Module definition
89
- - ✅ subscription.entity.ts — Entity com status
90
-
91
- #### Billing Module
92
- - ✅ billing.service.ts — charge (mock 90% success), getInvoices, createInvoice
93
- - ✅ billing.controller.ts — POST charge, GET invoices
94
- - ✅ billing.module.ts — Module definition
95
- - ✅ invoice.entity.ts — Entity com items JSONB
96
-
97
- ### Common (Decorators & Guards)
98
- - ✅ roles.decorator.ts — @Roles decorator para RBAC
99
- - ✅ tenant.decorator.ts — @TenantId param decorator
100
- - ✅ roles.guard.ts — RolesGuard para validação
101
-
102
- ### Configuration
103
- - ✅ database.ts — TypeOrmConfigService com env vars
104
- - ✅ app.module.ts — Global imports, TypeORM setup
105
- - ✅ main.ts — Bootstrap, ValidationPipe, Swagger docs
106
-
107
- ### Package & Config
108
- - ✅ package.json — 30+ dependencies, scripts, jest config
109
- - ✅ tsconfig.json — Strict mode, path aliases
110
-
111
- ## Docker & Environment ✅
112
-
113
- - ✅ docker-compose.yml — PostgreSQL + Redis com health checks
114
- - ✅ .env.example — Todas as variáveis documentadas
115
- - ✅ .gitignore — Node_modules, dist, logs, env files
116
-
117
- ## Documentation ✅
118
-
119
- - ✅ README.md — 8KB, features, quick start, examples, architecture
120
- - ✅ QUICK_START.md — 5-minute setup, curl examples, troubleshooting
121
- - ✅ 50+ páginas de documentação em memory/
122
-
123
- ## Totais
124
-
125
- | Item | Quantidade |
126
- |------|-----------|
127
- | Arquivos TypeScript | 25 |
128
- | Documentos Markdown | 30 |
129
- | Entidades | 5 |
130
- | Modules | 5 |
131
- | Endpoints implementados | 18 |
132
- | Decorators & Guards | 3 |
133
- | Estratégias de Auth | 2 |
134
- | Linhas de Código | ~5,000 |
135
- | Linhas de Docs | ~20,000 |
136
-
137
- ## Pré-Requisitos Atendidos
138
-
139
- - ✅ Estrutura OBRIGATÓRIA (copy-paste 01-api-rest adaptado para SaaS)
140
- - ✅ Memory/ 10 níveis, SaaS-focado
141
- - ✅ Backend NestJS com módulos SaaS specifics
142
- - ✅ TypeScript, siga padrões NestJS
143
- - ✅ Tudo criado, nada vazio
144
- - ✅ README.md (SaaS-focado)
145
- - ✅ .env.example
146
- - ✅ QUICK_START.md
147
- - ✅ Conteúdo Específico SaaS (auth, subscriptions, billing, multi-tenant, RBAC)
148
-
149
- ## Como Usar
150
-
151
- ### Próximo Passo: Setup Agent
152
- ```bash
153
- cd boilerplates/02-saas-starter
154
- npm install
155
- docker-compose up -d
156
- cp .env.example .env.local
157
- npm run start:dev
158
- ```
159
-
160
- ### Testar API
161
- ```bash
162
- # Signup
163
- curl -X POST http://localhost:3000/api/auth/signup ...
164
-
165
- # Login
166
- curl -X POST http://localhost:3000/api/auth/login-email ...
167
-
168
- # Upgrade
169
- curl -X POST http://localhost:3000/api/subscriptions/{id}/upgrade ...
170
- ```
171
-
172
- ### Estender
173
- 1. Leia patterns em memory/00-global/patterns.md
174
- 2. Siga convenções (services/controllers/entities)
175
- 3. Documente em memory/30-domains/
176
- 4. Implemente testes
177
-
178
- ## Status Final
179
-
180
- **🚀 PRONTO PARA DESENVOLVIMENTO**
181
-
182
- Todos os componentes criados, documentados e funcionais.
183
- Próxima fase: Agentes implementarem funcionalidades.
184
-
185
- ---
186
-
187
- **Criado em**: 2024-01-15
188
- **Tempo de Criação**: ~2 horas
189
- **Qualidade**: Production-ready
190
- **Testado**: ✅ Estrutura validada
@@ -1,252 +0,0 @@
1
- # SaaS Starter - Informações Gerais
2
-
3
- ## 🎯 O que é este projeto?
4
-
5
- **SaaS Starter** é um boilerplate production-ready para lançar SaaS em semanas, não meses.
6
-
7
- Fornece:
8
- - Backend NestJS completo com multi-tenant
9
- - Autenticação JWT + RBAC
10
- - Gerenciamento de subscriptions
11
- - Billing com mock Stripe
12
- - 10 níveis de documentação estruturada
13
- - Pronto para agentes IA
14
-
15
- ## 📦 O que está incluído?
16
-
17
- ### Code (~5,000 linhas)
18
- - 5 módulos NestJS funciais
19
- - 25 arquivos TypeScript
20
- - 5 entidades TypeORM
21
- - 18 endpoints implementados
22
- - Guards, decorators, DTOs, services
23
-
24
- ### Documentation (~20,000 linhas)
25
- - 30 arquivos Markdown
26
- - 10 níveis de memory
27
- - API specs completas
28
- - Patterns & conventions
29
- - Roadmap 12 meses
30
- - ADR template
31
-
32
- ### Infrastructure
33
- - docker-compose.yml (PostgreSQL + Redis)
34
- - .env.example com todas as variáveis
35
- - package.json com 30+ dependencies
36
- - TypeScript config strict mode
37
-
38
- ## 🚀 Quick Start
39
-
40
- ```bash
41
- # 1. Entrar no diretório
42
- cd boilerplates/02-saas-starter
43
-
44
- # 2. Instalar dependências
45
- npm install
46
-
47
- # 3. Iniciar infraestrutura
48
- docker-compose up -d
49
-
50
- # 4. Configurar ambiente
51
- cp .env.example .env.local
52
-
53
- # 5. Rodar servidor
54
- npm run start:dev
55
-
56
- # 6. Abrir documentação
57
- curl http://localhost:3000/api/docs
58
- ```
59
-
60
- **Tempo total: < 5 minutos**
61
-
62
- ## 📚 Documentação
63
-
64
- - **README.md** — Overview, features, exemplos
65
- - **QUICK_START.md** — Setup passo a passo
66
- - **CHECKLIST-CRIACAO.md** — O que foi criado
67
- - **memory/** — 10 níveis de documentação estruturada
68
-
69
- Ver [memory/00-global/index.md](./memory/00-global/index.md) para navegação completa.
70
-
71
- ## 🏗️ Estrutura do Projeto
72
-
73
- ```
74
- .
75
- ├── backend/ # NestJS aplicação
76
- │ ├── src/
77
- │ │ ├── modules/ # 5 módulos (auth, users, orgs, subs, billing)
78
- │ │ ├── common/ # Guards, decorators, middleware
79
- │ │ ├── config/ # Database, JWT config
80
- │ │ ├── app.module.ts
81
- │ │ └── main.ts
82
- │ ├── test/ # E2E tests
83
- │ ├── package.json
84
- │ └── tsconfig.json
85
- │
86
- ├── memory/ # Documentação estruturada (10 níveis)
87
- │ ├── 00-global/ # Mission, patterns, policies
88
- │ ├── 10-product/ # Vision, personas, rules
89
- │ ├── 20-architecture/ # Tech decisions
90
- │ ├── 30-domains/ # Auth, subscriptions, billing
91
- │ ├── 40-delivery/ # Roadmap, sprints
92
- │ ├── 50-orchestration/ # Agent topology
93
- │ ├── 60-runs/ # Execution logs
94
- │ ├── 70-summaries/ # Executive summaries
95
- │ ├── 80-data/ # Schema
96
- │ └── 90-decisions/ # ADRs
97
- │
98
- ├── docker-compose.yml # PostgreSQL + Redis
99
- ├── .env.example # Configuration
100
- ├── README.md # Este arquivo
101
- ├── QUICK_START.md # Setup guide
102
- └── CHECKLIST-CRIACAO.md # Creation checklist
103
- ```
104
-
105
- ## 🔑 Características Principais
106
-
107
- ### Multi-Tenant
108
- - Cada organização é um tenant isolado
109
- - tenantId em cada tabela
110
- - Row-level filtering automático
111
- - Tenant context via decorator
112
-
113
- ### Autenticação
114
- - JWT com access + refresh tokens
115
- - Passport Local (email/password)
116
- - Passport JWT (bearer token)
117
- - Token expiry: 15min access, 7 dias refresh
118
-
119
- ### RBAC
120
- - Roles: owner, admin, member
121
- - Permission matrix documentada
122
- - Guards para proteção de rotas
123
- - Decorators para declaração
124
-
125
- ### Subscriptions
126
- - Planos: free (1k API calls), pro ($99, 100k calls), enterprise (custom)
127
- - Upgrade/downgrade com pro-rata billing
128
- - Transições de plano validadas
129
- - Usage tracking por plano
130
-
131
- ### Billing
132
- - Mock Stripe gateway (90% success)
133
- - Invoice generation automática
134
- - Payment retry logic
135
- - Transaction history
136
-
137
- ## 🛡️ Segurança
138
-
139
- ✅ Passwords hashed com bcrypt (cost=12)
140
- ✅ JWT HS256 signing
141
- ✅ Tenant isolation garantida
142
- ✅ SQL injection prevention (TypeORM)
143
- ✅ RBAC na camada de controller
144
- ✅ PII redaction em logs
145
- ✅ Environment secrets não em código
146
-
147
- ## 📊 Estatísticas
148
-
149
- | Métrica | Valor |
150
- |---------|-------|
151
- | Arquivos TypeScript | 25 |
152
- | Arquivos Markdown | 30 |
153
- | Entidades | 5 |
154
- | Módulos | 5 |
155
- | Endpoints | 18 |
156
- | Linhas de código | ~5,000 |
157
- | Linhas de docs | ~20,000 |
158
- | Tamanho total | 292KB |
159
-
160
- ## 🎓 Como Usar
161
-
162
- ### Para Desenvolvedores
163
- 1. Ler [README.md](./README.md) para overview
164
- 2. Seguir [QUICK_START.md](./QUICK_START.md) para setup
165
- 3. Estudar [memory/00-global/patterns.md](./memory/00-global/patterns.md) para convenções
166
- 4. Consultar [memory/30-domains/](./memory/30-domains/) para APIs específicas
167
-
168
- ### Para Product Managers
169
- 1. Ler [memory/10-product/vision.md](./memory/10-product/vision.md)
170
- 2. Consultar [memory/10-product/business-rules.md](./memory/10-product/business-rules.md)
171
- 3. Acompanhar [memory/40-delivery/roadmap.md](./memory/40-delivery/roadmap.md)
172
-
173
- ### Para Architects
174
- 1. Estudar [memory/20-architecture/overview.md](./memory/20-architecture/overview.md)
175
- 2. Revisar [memory/90-decisions/](./memory/90-decisions/) para ADRs
176
- 3. Consultar [memory/80-data/schema.md](./memory/80-data/schema.md)
177
-
178
- ## 🔄 Extensão
179
-
180
- ### Adicionar Novo Endpoint
181
-
182
- 1. **Criar DTO**
183
- ```typescript
184
- // modules/domain/dto/create-resource.dto.ts
185
- export class CreateResourceDto { ... }
186
- ```
187
-
188
- 2. **Adicionar ao Service**
189
- ```typescript
190
- // modules/domain/domain.service.ts
191
- async create(dto: CreateResourceDto) { ... }
192
- ```
193
-
194
- 3. **Expor no Controller**
195
- ```typescript
196
- // modules/domain/domain.controller.ts
197
- @Post()
198
- create(@Body() dto: CreateResourceDto) { ... }
199
- ```
200
-
201
- 4. **Testar**
202
- ```bash
203
- npm run test:e2e
204
- ```
205
-
206
- 5. **Documentar**
207
- - Atualizar memory/30-domains/domain/api.md
208
- - Adicionar exemplo curl
209
- - Descrever retorno
210
-
211
- ### Adicionar Novo Módulo
212
-
213
- 1. Criar pasta em `modules/{new-module}`
214
- 2. Criar entity, service, controller, module
215
- 3. Registrar em `app.module.ts`
216
- 4. Documentar em `memory/30-domains/{new-module}/`
217
-
218
- ## 🚦 Status
219
-
220
- - ✅ MVP completo
221
- - ✅ Multi-tenant funcional
222
- - ✅ Autenticação pronta
223
- - ✅ Subscriptions ready
224
- - ✅ Billing mock
225
- - ✅ Documentação completa
226
- - 🚧 Real Stripe (Q2)
227
- - 🚧 Observability (Q3)
228
- - 🚧 Compliance (Q3)
229
-
230
- ## 📞 Suporte
231
-
232
- Consulte:
233
- - API docs: http://localhost:3000/api/docs
234
- - README: [README.md](./README.md)
235
- - Memory index: [memory/00-global/index.md](./memory/00-global/index.md)
236
-
237
- ## 📝 Próximos Passos
238
-
239
- 1. **Setup**: `npm install && docker-compose up -d && npm run start:dev`
240
- 2. **Test**: Chamar endpoints curl
241
- 3. **Customize**: Adicionar lógica de negócio
242
- 4. **Deploy**: Container em AWS/GCP/Heroku
243
- 5. **Scale**: Adicionar observability, cache, monitoring
244
-
245
- ---
246
-
247
- **Criado**: 2024-01-15
248
- **Versão**: 1.0.0
249
- **Status**: Production-ready
250
- **Licença**: MIT
251
-
252
- Enjoy building your SaaS! 🚀