forjajs 5.0.0 → 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 (171) hide show
  1. package/CHANGELOG.md +68 -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/create-memory-nest-kit.js +0 -0
  50. package/dist/bin/forja.js +0 -0
  51. package/dist/bin/init-project.js +1 -0
  52. package/dist/lib/core/journey.js +10 -0
  53. package/dist/lib/generators/memory-generator.d.ts +0 -11
  54. package/dist/lib/generators/memory-generator.js +5 -161
  55. package/dist/lib/generators/readme-generator.js +1 -1
  56. package/dist/lib/llm/json-output.d.ts +14 -0
  57. package/dist/lib/llm/json-output.js +77 -0
  58. package/dist/lib/project-upgrade.d.ts +0 -4
  59. package/dist/lib/project-upgrade.js +19 -1
  60. package/dist/lib/project-wiring.d.ts +8 -0
  61. package/dist/lib/project-wiring.js +74 -2
  62. package/dist/lib/validators/structure-validator.js +0 -1
  63. package/dist/packages/llm/src/index.js +12 -2
  64. package/dist/scripts/llm-fit.js +23 -1
  65. package/dist/scripts/project-upgrade.js +9 -6
  66. package/docs/init-project.md +1 -1
  67. package/docs/llm-fit-loop.md +16 -0
  68. package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
  69. package/memory/90-decisions/0088-templates-validados.md +3 -0
  70. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  71. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  72. package/package.json +2 -2
  73. package/specs/skills-do-projeto/plan.md +40 -0
  74. package/specs/skills-do-projeto/spec.md +63 -0
  75. package/specs/skills-do-projeto/tasks.md +27 -0
  76. package/templates/project/AGENTS.md +9 -0
  77. package/templates/project/agents/context-engineer.md +3 -0
  78. package/templates/project/agents/governance.md +3 -0
  79. package/templates/project/agents/marketing.md +3 -0
  80. package/templates/project/agents/orchestrator.md +3 -0
  81. package/templates/project/agents/product.md +3 -0
  82. package/templates/project/agents/sdd-architect.md +3 -0
  83. package/templates/project/skills/README.md +14 -0
  84. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  85. package/templates/project/skills/api-design/SKILL.md +77 -0
  86. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  87. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  88. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  89. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  90. package/templates/project/skills/commit-message/SKILL.md +143 -0
  91. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  92. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  93. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  94. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  95. package/templates/project/skills/event-storming/SKILL.md +95 -0
  96. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  97. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  98. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  99. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  100. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  101. package/templates/project/skills/observability/SKILL.md +93 -0
  102. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  103. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  104. package/templates/project/skills/pull-request/SKILL.md +101 -0
  105. package/templates/project/skills/query-performance/SKILL.md +83 -0
  106. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  107. package/templates/project/skills/release-notes/SKILL.md +87 -0
  108. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  109. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  110. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  111. package/templates/project/skills/testing/SKILL.md +109 -0
  112. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  113. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  114. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  115. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  116. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  117. package/templates/project/skills/web-performance/SKILL.md +72 -0
  118. package/boilerplates/02-saas-starter/.env.example +0 -25
  119. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  120. package/boilerplates/02-saas-starter/INFO.md +0 -252
  121. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  122. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  123. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  124. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  125. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  126. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  127. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  128. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  129. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  130. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  131. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  132. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  133. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  134. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  135. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  136. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  137. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  138. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  139. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  140. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  141. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  142. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  143. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  144. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  145. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  146. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  147. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  148. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  149. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  150. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  151. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  152. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  153. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  154. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  155. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  156. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  157. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  158. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  159. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  160. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  161. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  162. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  163. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  164. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  165. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  166. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  167. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  168. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  169. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  170. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  171. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -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:
@@ -1,137 +1,20 @@
1
- # Billing Domain Context
1
+ # Billing — contexto
2
2
 
3
- ## O que é Billing neste SaaS?
3
+ Cada organização tem uma **assinatura** de um **plano** (`free`, `pro`, `enterprise`). O período
4
+ de cobrança é o mês civil em UTC. Uma **fatura** cobra um período de uma assinatura.
4
5
 
5
- Billing cuida de:
6
- 1. Processar pagamentos (mock Stripe para MVP)
7
- 2. Gerar invoices
8
- 3. Registrar transações
9
- 4. Retry policy para falhas
10
- 5. Webhooks para eventos de billing
6
+ ## Regras
11
7
 
12
- ## Fluxo de Pagamento
8
+ - Preços e limites estão em `src/billing/domain/plan.ts`, em centavos inteiros. O valor da fatura
9
+ vem dali, nunca do cliente.
10
+ - Transições: `free → pro | enterprise`, `pro → free | enterprise`; `enterprise` é contratual
11
+ (mudanças fora da API). Transição proibida responde 422 e não altera nada.
12
+ - Mudar o plano é só da `owner`.
13
+ - Uma fatura por organização e período: emitir de novo devolve a mesma (índice único no banco).
14
+ Valor zero nasce `paid`; o resto nasce `open` até o gateway confirmar.
15
+ - Fatura de outra organização responde 404 (não 403: não confirma que existe).
13
16
 
14
- ```
15
- Usuário faz upgrade
16
- ↓
17
- Billing Agent recebe request
18
- ↓
19
- Validar payment method (card)
20
- ↓
21
- Chamar payment gateway (mock Stripe)
22
- ↓
23
- [Sucesso?]
24
- SIM → Criar invoice, registrar transação
25
- Enviar email de receipt
26
- Webhook callback
27
- NÃO → Retry logic (3 tentativas em 14 dias)
28
- Notificar usuário
29
- Tentar method alternativo
30
- ```
17
+ ## Onde está
31
18
 
32
- ## Payment Gateway Mock
33
-
34
- Para MVP, simulamos Stripe com:
35
- - Status: "succeeded" (90%) ou "failed" (10%)
36
- - Transações em banco de dados
37
- - Invoice generation automática
38
-
39
- ```typescript
40
- // Mock Stripe response
41
- {
42
- "id": "pi_1234567890",
43
- "amount": 9900,
44
- "currency": "usd",
45
- "status": "succeeded",
46
- "payment_method": {
47
- "type": "card",
48
- "card": { "last4": "4242", "brand": "visa" }
49
- },
50
- "created": 1705330200
51
- }
52
- ```
53
-
54
- ## Invoice Structure
55
-
56
- ```json
57
- {
58
- "id": "inv_xyz",
59
- "organizationId": "org-uuid",
60
- "invoiceNumber": "INV-2024-001",
61
- "amount": 99.00,
62
- "currency": "usd",
63
- "status": "paid",
64
- "description": "Pro Plan - January 2024",
65
- "items": [
66
- {
67
- "description": "Pro Plan",
68
- "quantity": 1,
69
- "unitPrice": 99.00,
70
- "amount": 99.00
71
- },
72
- {
73
- "description": "Additional User (4 seats)",
74
- "quantity": 4,
75
- "unitPrice": 10.00,
76
- "amount": 40.00
77
- }
78
- ],
79
- "issuedAt": "2024-01-01T00:00:00Z",
80
- "dueDate": "2024-01-15T00:00:00Z",
81
- "paidAt": "2024-01-01T10:30:00Z"
82
- }
83
- ```
84
-
85
- ## Regras de Negócio
86
-
87
- 1. **Retry Policy**:
88
- - 1ª tentativa: Imediato
89
- - 2ª tentativa: 3 dias depois
90
- - 3ª tentativa: 10 dias depois
91
- - Após 3 falhas: Suspender acc, enviar notificação
92
-
93
- 2. **Invoice Generation**:
94
- - Automático após pagamento bem-sucedido
95
- - Inclui subscription + add-ons (extra seats)
96
- - PDF gerado async (futura)
97
-
98
- 3. **Refund Policy**:
99
- - Dentro de 14 dias: Full refund
100
- - Após 14 dias: Pro-rata refund
101
- - Processado em 5-7 dias
102
-
103
- 4. **Tax Calculation** (Futura):
104
- - US: Sales tax por estado
105
- - EU: VAT aplicado
106
- - B2B: Reverse charge
107
-
108
- 5. **Currency Handling**:
109
- - MVP: USD apenas
110
- - Futuro: Multi-currency com taxa de câmbio
111
-
112
- ## Métricas Importantes
113
-
114
- - **Failed payment rate**: % de pagamentos rejeitados
115
- - **Churn via failed payment**: % de cancelamentos por payment failure
116
- - **Refund rate**: % de refunds vs total transactions
117
- - **Invoice delivery**: % enviados < 1 min
118
-
119
- ## Status Atual
120
-
121
- - ✅ Invoice entity
122
- - ✅ Payment mock (Stripe-like)
123
- - ✅ Transaction history
124
- - ✅ Invoice generation
125
- - 🚧 PDF generation
126
- - 🚧 Real Stripe integration
127
- - 🚧 Webhook handling
128
- - 🚧 Tax calculation
129
- - 🚧 Multi-currency
130
-
131
- ## Próximos Steps
132
-
133
- 1. Implementar real Stripe integration
134
- 2. Adicionar webhook handlers
135
- 3. Gerar PDFs de invoices
136
- 4. Implementar tax calculation
137
- 5. Adicionar refund endpoints
19
+ `src/billing/domain/` (planos, agregado `Subscription`, portas) ·
20
+ `application/billing.service.ts` · `adapters/persistence/` (TypeORM).
@@ -0,0 +1,20 @@
1
+ # Identity — contexto
2
+
3
+ **Organização** é o tenant: tudo que pertence a um cliente carrega o `tenantId` dela. Uma
4
+ **pessoa usuária** pertence a exatamente uma organização e tem papéis: `owner` (quem criou;
5
+ decide o plano), `admin` (gerencia membros e faturas), `member`.
6
+
7
+ ## Regras
8
+
9
+ - Cadastro cria a organização e a dona na mesma transação. O slug deriva do nome; se já existe,
10
+ ganha um sufixo aleatório.
11
+ - E-mail é único no sistema inteiro, comparado em minúsculas.
12
+ - Senha: mínimo 12 caracteres com minúscula, maiúscula e dígito; guardada com scrypt.
13
+ - Login errado e e-mail inexistente dão a mesma resposta, no mesmo tempo.
14
+ - Access token (15 min) e refresh token (7 dias) usam segredos distintos; um não vale como o outro.
15
+ O refresh relê a pessoa usuária: desativada, não renova.
16
+
17
+ ## Onde está
18
+
19
+ `src/identity/domain/` (modelo e porta) · `application/auth.service.ts` (casos de uso) ·
20
+ `src/platform/auth/` (tokens, guards, papéis).
@@ -44,23 +44,22 @@ forja project:new meu-projeto # e use boilerplates/01-api-rest/ como arquitetu
44
44
  ---
45
45
 
46
46
  ### 💼 2. SaaS
47
- **Para**: Aplicações multi-tenant, subscriptions, billing
47
+ **Para**: SaaS B2B multi-tenant com assinatura e faturamento
48
48
 
49
49
  ```bash
50
- forja project:new meu-projeto # e use boilerplates/02-saas-starter/ como arquitetura de referência
50
+ forja project:new meu-projeto --template saas-starter # template validado (NestJS 12, Vitest)
51
51
  ```
52
52
 
53
53
  **Inclui**:
54
- - Autenticação com planos
55
- - Subscription management
56
- - Billing mock
57
- - Organização multi-tenant
58
- - Role-based access control
59
- - Testes
54
+ - Organização = tenant; o tenant vem sempre do token, recurso de outro tenant responde 404
55
+ - Cadastro, login e refresh (scrypt, access e refresh com segredos distintos), papéis owner/admin/member
56
+ - Planos com transições validadas no domínio, preço em centavos vindo da tabela (nunca do cliente)
57
+ - Fatura mensal idempotente por período; gateway de pagamento fica como adapter seu
58
+ - A API não sobe sem os segredos configurados (nada de segredo padrão)
60
59
 
61
- **Use quando**: Construir SaaS com múltiplos clientes, subscriptions
60
+ **Use quando**: Construir SaaS com múltiplos clientes, papéis e assinaturas
62
61
 
63
- [Abrir 📂](./02-saas)
62
+ [Abrir 📂](./02-saas-starter)
64
63
 
65
64
  ---
66
65
 
File without changes
package/dist/bin/forja.js CHANGED
File without changes
@@ -362,6 +362,7 @@ Exemplos:
362
362
  forja project:new meu-app
363
363
  forja project:new meu-app -- --ai claude,codex --skip-backend
364
364
  forja project:new pedidos -- --template clean-arch
365
+ forja project:new minha-saas -- --template saas-starter
365
366
  `);
366
367
  process.exit(projectName === undefined && process.argv.length > 2 ? 1 : 0);
367
368
  }
@@ -70,6 +70,16 @@ export function runJourney(opts) {
70
70
  catch { /* reportado abaixo */ }
71
71
  const wiringFails = (wiring?.checks ?? []).filter((c) => c.status === 'fail').map((c) => `${c.id}: ${c.detail}`);
72
72
  add('project:wire', r.code === 0 && wiring?.ok === true, wiring ? (wiringFails.join('; ') || `${wiring.checks.length} checks ok`) : firstLine(r.out));
73
+ // SPEC-051: as skills chegam onde Claude e Codex as procuram.
74
+ const skillCount = (rel) => { try {
75
+ return fs.readdirSync(path.join(proj, rel)).filter((n) => fs.existsSync(path.join(proj, rel, n, 'SKILL.md'))).length;
76
+ }
77
+ catch {
78
+ return 0;
79
+ } };
80
+ const claudeSkills = skillCount(path.join('.claude', 'skills'));
81
+ const agentSkills = skillCount(path.join('.agents', 'skills'));
82
+ add('skills', claudeSkills >= 34 && agentSkills >= 34, `${claudeSkills} em .claude/skills, ${agentSkills} em .agents/skills`);
73
83
  r = forja(['status'], proj);
74
84
  add('status', r.code === 0 && /memória indexada: sim/.test(r.out), /memória indexada: sim/.test(r.out) ? 'memória indexada de nascença' : firstLine(r.out));
75
85
  r = forja(['spec:new', 'pagamentos'], proj);
@@ -48,16 +48,6 @@ export declare function getAllMemoryTemplates(): {
48
48
  'agents/dba.md': string;
49
49
  'agents/security.md': string;
50
50
  'agents/reviewer.md': string;
51
- 'skills/triage-task/SKILL.md': string;
52
- 'skills/context-compaction/SKILL.md': string;
53
- 'skills/handoff/SKILL.md': string;
54
- 'skills/nest-api/SKILL.md': string;
55
- 'skills/self-healing/SKILL.md': string;
56
- 'skills/validate-handoff/SKILL.md': string;
57
- 'skills/ui-fidelity/SKILL.md': string;
58
- 'skills/reasoning-protocol/SKILL.md': string;
59
- 'skills/llm-provider-routing/SKILL.md': string;
60
- 'skills/MANIFEST.json': string;
61
51
  'prompts/project-prompt-base.md': string;
62
52
  'prompts/multi-agent-orchestrator.md': string;
63
53
  'prompts/worker-task-template.md': string;
@@ -67,7 +57,6 @@ export declare function getAllMemoryTemplates(): {
67
57
  'scripts/build-context-pack.mjs': string;
68
58
  'scripts/append-handoff.mjs': string;
69
59
  'scripts/check-memory-maps.mjs': string;
70
- 'scripts/lib/skill-loader.mjs': string;
71
60
  'scripts/memory-vacuum.mjs': string;
72
61
  'scripts/memory-watcher.mjs': string;
73
62
  };
@@ -272,7 +272,7 @@ Mantenha resumos curtos por dominio para carregamento rapido de contexto.
272
272
  Armazenar indice operacional da documentacao para busca e continuidade de contexto.
273
273
 
274
274
  ## Fonte da verdade
275
- - Arquivos Markdown em memory/, docs/, agents/, skills/, prompts/
275
+ - Arquivos Markdown em memory/, docs/, agents/, prompts/
276
276
 
277
277
  ## Banco
278
278
  - SQLite em .memory/sqlite/context.db
@@ -356,144 +356,9 @@ Planejamento, decomposicao de tarefas, atribuicao de ownership e consolidacao.
356
356
  - cobertura de testes
357
357
  `,
358
358
  };
359
- /**
360
- * Gera estrutura de skills
361
- */
362
- const skillTemplates = {
363
- 'skills/triage-task/SKILL.md': `# Skill: Triage de Tarefa
364
-
365
- ## Objetivo
366
- Classificar demanda em: rapido, medio, complexo.
367
-
368
- ## Saida
369
- - resumo
370
- - risco
371
- - owner sugerido
372
- - fatias de execucao
373
- `,
374
- 'skills/context-compaction/SKILL.md': `# Skill: Compactacao de Contexto
375
-
376
- ## Objetivo
377
- Gerar resumo operacional sem perder decisoes chave.
378
-
379
- ## Regras
380
- - manter fatos verificaveis
381
- - remover redundancia
382
- - preservar links para fontes internas
383
- `,
384
- 'skills/handoff/SKILL.md': `# Skill: Handoff
385
-
386
- ## Template
387
- - contexto
388
- - alteracoes
389
- - riscos
390
- - pendencias
391
- - proximo agente
392
- `,
393
- 'skills/nest-api/SKILL.md': `# Skill: Nest API
394
-
395
- ## Checklist
396
- - modulo criado
397
- - dto com validacao
398
- - controller + service
399
- - testes
400
- `,
401
- 'skills/self-healing/SKILL.md': `# Skill: Auto-Diagnóstico (Self-Healing)
402
-
403
- ## Objetivo
404
- Resolver falhas de build, testes ou tipos sem intervenção humana.
405
-
406
- ## Fluxo
407
- 1. Analisar a stack trace completa do erro.
408
- 2. Identificar se é: erro de sintaxe, falta de dependência, erro de tipo ou lógica.
409
- 3. Consultar documentação interna ou padrões do projeto.
410
- 4. Propor correção mínima e rodar validação novamente.
411
- `,
412
- 'skills/validate-handoff/SKILL.md': `# Skill: Validação e Review de Segurança (Gatekeeper)
413
-
414
- ## Objetivo
415
- Atuar como Gatekeeper final para garantir que nenhum código inseguro ou incompleto entre no pipeline.
416
-
417
- ## Protocolo de Review (Obrigatório)
418
- Antes de aceitar um handoff, o Reviewer deve validar:
419
-
420
- 1. **Compliance de Raciocínio**: O Worker preencheu o bloco \`## Raciocínio Estruturado\`? (Se não, rejeite imediatamente).
421
- 2. **Scan de Segurança**:
422
- - Há logs sensíveis (PII, tokens) sendo impressos?
423
- - As validações de input estão no DTO?
424
- 3. **Verificação de Handoff**:
425
- - Os arquivos listados no handoff condizem com o diff real?
426
- - Existem pendências (riscos) não documentadas?
427
-
428
- ## Saída do Reviewer
429
- - [ ] Aprovado (Status: \`done\` no DB)
430
- - [ ] Rejeitado (Status: \`blocked\` + pendências listadas)
431
- `,
432
- 'skills/ui-fidelity/SKILL.md': `# Skill: Fidelidade Visual
433
-
434
- ## Objetivo
435
- Garantir que a UI segue padrões de elite.
436
-
437
- ## Instrução
438
- 1. Consultar a biblioteca \`design-md/\` para inspiração de marca/padrão.
439
- 2. Comparar o código gerado com os padrões de espaçamento, tipografia e cores da referência.
440
- 3. Ajustar CSS/Componentes para atingir qualidade visual de nível mundial.
441
- `,
442
- 'skills/reasoning-protocol/SKILL.md': `# Skill: Raciocínio Estruturado (Chain-of-Thought)
443
-
444
- ## Objetivo
445
- Reduzir erros de implementação através de análise lógica explícita.
446
-
447
- ## Protocolo Obrigatório
448
- Antes de qualquer código ou plano de ação, preencha o bloco \`## Raciocínio Estruturado\`:
449
-
450
- 1. **Entendimento**: O que foi pedido e qual o impacto no sistema?
451
- 2. **Restrições**: Quais arquivos NÃO posso tocar? Quais padrões devo seguir?
452
- 3. **Alternativas**: Existe mais de uma forma de fazer? Por que escolhi esta?
453
- 4. **Plano de Ataque**: Passo-a-passo lógico da implementação.
454
- `,
455
- 'skills/llm-provider-routing/SKILL.md': `# Skill: Roteamento de LLM Providers
456
-
457
- ## Objetivo
458
- Selecionar e configurar uma LLM por papel sem amarrar o projeto a um unico fornecedor, usando o ciclo verificável do Forja.
459
-
460
- ## Quando usar
461
- - O usuario pedir DeepSeek, MiniMax, Mistral, Qwen, Ollama, OpenRouter, Together, Groq, xAI, Cohere, Perplexity ou outro provider.
462
- - Um papel precisar trocar de modelo por custo, cota, latencia, contexto, privacidade ou qualidade.
463
- - Uma CLI/API externa precisar entrar no fluxo de handoffs sem alterar o SDD.
464
-
465
- ## Regras
466
- - Preferir providers locais para tarefas sensiveis quando o modelo disponivel for suficiente.
467
- - Usar \`manual\` quando o provider nao tiver CLI local confiavel.
468
- - Registrar perfis no workspace em \`.context/llm-profiles.json\` com \`provider\`, \`model\`, \`command\`, \`commandArgs\`, \`roles\`, \`taskTypes\`, \`privacy\` e \`enabled\`.
469
- - Nao assumir que uma CLI existe: validar o binario ou documentar o comando esperado.
470
- - Nao colocar API keys em memoria, specs, handoffs ou logs.
471
-
472
- ## Checklist
473
- 1. Identificar papel e tipo de tarefa.
474
- 2. Inicializar ou revisar os perfis com \`forja llm:profiles:init\`.
475
- 3. Preencher \`command\` com um único executável e \`commandArgs\` para argumentos fixos; nunca use shell ou grave credenciais.
476
- 4. Rodar \`forja llm:probe <perfil>\` antes de delegar uma sprint inteira.
477
- 5. Consultar \`forja llm:recommend --role <papel> --task <tipo>\` e aprovar explicitamente a escolha.
478
- 6. Executar \`forja llm:run --profile <perfil> --task <arquivo>\` e avaliar com \`forja llm:eval --scope model --id <provider:model>\`.
479
- 7. Registrar handoff Hermes quando a troca impactar entrega.
480
- `,
481
- 'skills/MANIFEST.json': `{
482
- "version": "0.5.0",
483
- "skills": [
484
- { "id": "triage", "path": "skills/triage-task/SKILL.md", "description": "Classificação de tarefas" },
485
- { "id": "compaction", "path": "skills/context-compaction/SKILL.md", "description": "Compactação de memória" },
486
- { "id": "handoff", "path": "skills/handoff/SKILL.md", "description": "Protocolo de transição" },
487
- { "id": "nest-api", "path": "skills/nest-api/SKILL.md", "description": "Geração de endpoints NestJS" },
488
- { "id": "self-healing", "path": "skills/self-healing/SKILL.md", "description": "Resolução autônoma de erros" },
489
- { "id": "validate-handoff", "path": "skills/validate-handoff/SKILL.md", "description": "Checklist de qualidade de handoff" },
490
- { "id": "ui-fidelity", "path": "skills/ui-fidelity/SKILL.md", "description": "Auditoria estética de UI" },
491
- { "id": "reasoning", "path": "skills/reasoning-protocol/SKILL.md", "description": "Protocolo de raciocínio lógico" },
492
- { "id": "llm-provider-routing", "path": "skills/llm-provider-routing/SKILL.md", "description": "Roteamento multi-LLM por papel" }
493
- ]
494
- }
495
- `,
496
- };
359
+ // Skills do projeto: instaladas pelo project:wire em .claude/skills/ e .agents/skills/ a partir de
360
+ // templates/project/skills/ (SPEC-051). As 9 "skills" de esboço que viviam aqui ficavam em skills/
361
+ // sem frontmatter, onde nenhuma IA as carregava.
497
362
  /**
498
363
  * Gera estrutura de prompts
499
364
  */
@@ -691,26 +556,6 @@ if (dangling) {
691
556
  }
692
557
  console.log('');
693
558
  console.log('OK -- os mapas de memoria batem com o codigo.');
694
- `,
695
- 'scripts/lib/skill-loader.mjs': `import fs from 'node:fs';
696
- import path from 'node:path';
697
- import { fileURLToPath } from 'node:url';
698
-
699
- const __filename = fileURLToPath(import.meta.url);
700
- const __dirname = path.dirname(__filename);
701
- const root = path.resolve(__dirname, '..', '..');
702
-
703
- export function loadSkills() {
704
- const manifestPath = path.join(root, 'skills', 'MANIFEST.json');
705
- if (!fs.existsSync(manifestPath)) return [];
706
- const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
707
- return manifest.skills;
708
- }
709
-
710
- export function getSkill(id) {
711
- const skills = loadSkills();
712
- return skills.find(s => s.id === id);
713
- }
714
559
  `,
715
560
  'scripts/memory-vacuum.mjs': `import fs from 'node:fs';
716
561
  import path from 'node:path';
@@ -758,7 +603,7 @@ const __filename = fileURLToPath(import.meta.url);
758
603
  const __dirname = path.dirname(__filename);
759
604
  const root = path.resolve(__dirname, '..');
760
605
 
761
- const watchDirs = ['memory', 'agents', 'skills', 'prompts', 'docs'];
606
+ const watchDirs = ['memory', 'agents', 'prompts', 'docs'];
762
607
  let timeout = null;
763
608
 
764
609
  console.log('👀 Memory Watcher iniciado...');
@@ -787,7 +632,6 @@ export function getAllMemoryTemplates() {
787
632
  return {
788
633
  ...memoryTemplates,
789
634
  ...agentTemplates,
790
- ...skillTemplates,
791
635
  ...promptTemplates,
792
636
  ...configTemplates,
793
637
  ...scriptTemplates,
@@ -28,7 +28,7 @@ Este projeto segue uma arquitetura modular com:
28
28
  - 90-decisions/ — ADRs
29
29
 
30
30
  - **agents/** — Definição de agentes especializados
31
- - **skills/** — Capacidades reutilizáveis
31
+ - **.claude/skills/** e **.agents/skills/** — Skills por papel (instaladas pelo \`forja project:wire\`)
32
32
  - **prompts/** — Instruções por contexto
33
33
  - **backend/** — API NestJS (se gerado)
34
34
 
@@ -0,0 +1,14 @@
1
+ import type { LlmExecutionResult } from '../../packages/llm/src/index.ts';
2
+ import type { NormalizedLlmResult } from './codex-output.ts';
3
+ /**
4
+ * Normaliza `gemini -o json` (ADR-0090): um objeto `{ session_id, response, stats, error }`, com o uso
5
+ * por modelo em `stats.models[<modelo>].tokens.{prompt, candidates, cached}` — formato lido do
6
+ * JsonFormatter do próprio Gemini CLI. Campos ausentes viram `undefined`, nunca zero inventado.
7
+ */
8
+ export declare function normalizeGeminiResult(result: LlmExecutionResult): NormalizedLlmResult;
9
+ /**
10
+ * Normaliza `cursor-agent -p --output-format json`: o mesmo envelope do Claude
11
+ * (`type: "result"`, `subtype`, `is_error`, `result`, `session_id`, `usage`). O Cursor usa
12
+ * `inputTokens`/`outputTokens` em camelCase em alguns caminhos; os nomes são alinhados antes.
13
+ */
14
+ export declare function normalizeCursorResult(result: LlmExecutionResult): NormalizedLlmResult;
@@ -0,0 +1,77 @@
1
+ import { normalizeClaudeResult } from './claude-output.js';
2
+ /**
3
+ * Normaliza `gemini -o json` (ADR-0090): um objeto `{ session_id, response, stats, error }`, com o uso
4
+ * por modelo em `stats.models[<modelo>].tokens.{prompt, candidates, cached}` — formato lido do
5
+ * JsonFormatter do próprio Gemini CLI. Campos ausentes viram `undefined`, nunca zero inventado.
6
+ */
7
+ export function normalizeGeminiResult(result) {
8
+ let parsed;
9
+ try {
10
+ parsed = JSON.parse(result.stdout);
11
+ }
12
+ catch {
13
+ return withError(result, '', undefined, undefined, 'INVALID_PROVIDER_OUTPUT');
14
+ }
15
+ if (!record(parsed))
16
+ return withError(result, '', undefined, undefined, 'INVALID_PROVIDER_OUTPUT');
17
+ const answer = typeof parsed.response === 'string' ? parsed.response : undefined;
18
+ const sessionId = typeof parsed.session_id === 'string' ? parsed.session_id : undefined;
19
+ let usage;
20
+ const models = record(parsed.stats) && record(parsed.stats.models) ? Object.values(parsed.stats.models) : [];
21
+ let input = 0, output = 0, cached = 0, seen = false;
22
+ for (const m of models) {
23
+ if (!record(m) || !record(m.tokens))
24
+ continue;
25
+ const t = m.tokens;
26
+ if (tokens(t.prompt) && tokens(t.candidates)) {
27
+ seen = true;
28
+ input += t.prompt;
29
+ output += t.candidates + (tokens(t.thoughts) ? t.thoughts : 0);
30
+ if (tokens(t.cached))
31
+ cached += t.cached;
32
+ }
33
+ }
34
+ if (seen)
35
+ usage = { inputTokens: input, outputTokens: output, ...(cached ? { cachedInputTokens: cached } : {}) };
36
+ const errorCode = result.errorCode
37
+ ?? (result.exitCode !== 0 ? 'COMMAND_FAILED'
38
+ : parsed.error !== undefined ? 'PROVIDER_FAILED'
39
+ : answer === undefined ? 'INVALID_PROVIDER_OUTPUT'
40
+ : undefined);
41
+ return withError(result, answer ?? '', sessionId, usage, errorCode);
42
+ }
43
+ /**
44
+ * Normaliza `cursor-agent -p --output-format json`: o mesmo envelope do Claude
45
+ * (`type: "result"`, `subtype`, `is_error`, `result`, `session_id`, `usage`). O Cursor usa
46
+ * `inputTokens`/`outputTokens` em camelCase em alguns caminhos; os nomes são alinhados antes.
47
+ */
48
+ export function normalizeCursorResult(result) {
49
+ let parsed;
50
+ try {
51
+ parsed = JSON.parse(result.stdout);
52
+ }
53
+ catch {
54
+ return withError(result, '', undefined, undefined, 'INVALID_PROVIDER_OUTPUT');
55
+ }
56
+ if (record(parsed) && record(parsed.usage)) {
57
+ const u = parsed.usage;
58
+ parsed = {
59
+ ...parsed,
60
+ usage: {
61
+ input_tokens: u.input_tokens ?? u.inputTokens,
62
+ output_tokens: u.output_tokens ?? u.outputTokens,
63
+ cache_read_input_tokens: u.cache_read_input_tokens ?? u.cacheReadTokens,
64
+ },
65
+ };
66
+ }
67
+ return normalizeClaudeResult({ ...result, stdout: JSON.stringify(parsed) });
68
+ }
69
+ function withError(result, stdout, sessionId, usage, errorCode) {
70
+ return { ...result, stdout, sessionId, usage, exitCode: result.exitCode !== 0 ? result.exitCode : errorCode ? 1 : 0, ...(errorCode ? { errorCode } : {}) };
71
+ }
72
+ function record(value) {
73
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
74
+ }
75
+ function tokens(value) {
76
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
77
+ }
@@ -19,10 +19,6 @@ export interface UpgradePlan {
19
19
  /** Presentes nos dois — não tocados (podem ter edição do usuário). */
20
20
  existing: number;
21
21
  }
22
- /**
23
- * Planeja o upgrade: o que o scaffold fresco tem que o projeto-alvo não tem. **Só adições** — nunca
24
- * lista sobrescritas, porque um arquivo existente é território do usuário.
25
- */
26
22
  export declare function planUpgrade(freshRoot: string, targetRoot: string, env?: UpgradeEnv): UpgradePlan;
27
23
  /** Aplica o plano: copia as peças novas para o alvo, criando diretórios. Nunca sobrescreve. */
28
24
  export declare function applyUpgrade(freshRoot: string, targetRoot: string, plan: UpgradePlan, env?: UpgradeEnv): string[];
@@ -47,8 +47,26 @@ export function listFiles(root, env = defaultEnv) {
47
47
  * Planeja o upgrade: o que o scaffold fresco tem que o projeto-alvo não tem. **Só adições** — nunca
48
48
  * lista sobrescritas, porque um arquivo existente é território do usuário.
49
49
  */
50
+ /** Código do usuário: nunca é scaffold a trazer, mesmo que a referência o tenha. */
51
+ const USER_CODE = /^(backend|frontend|apps|packages|src)\//;
52
+ /** Conteúdo de exemplo do scaffold que só faz sentido num projeto que ainda não tem o seu. */
53
+ const SAMPLE_DOMAINS = /^memory\/30-domains\/(?!shared\/)[^/]+\//;
54
+ const NEST_ONLY = /^(agents\/backend-nest\.md|skills\/nest-api\/)/;
55
+ function usesNest(targetRoot, env) {
56
+ return ['package.json', 'backend/package.json'].some((rel) => {
57
+ try {
58
+ return /"@nestjs\/core"/.test(String(env.fs.readFileSync(path.join(targetRoot, rel), 'utf8')));
59
+ }
60
+ catch {
61
+ return false;
62
+ }
63
+ });
64
+ }
50
65
  export function planUpgrade(freshRoot, targetRoot, env = defaultEnv) {
51
- const fresh = listFiles(freshRoot, env);
66
+ // Domínios de exemplo (auth, billing…) num projeto que já existe confundem a IA: ela os leria como
67
+ // parte do produto. Idem agente/skill de NestJS num backend que não é Nest.
68
+ const nest = usesNest(targetRoot, env);
69
+ const fresh = listFiles(freshRoot, env).filter((rel) => !USER_CODE.test(rel) && !SAMPLE_DOMAINS.test(rel) && !(!nest && NEST_ONLY.test(rel)));
52
70
  const newFiles = [];
53
71
  let existing = 0;
54
72
  for (const rel of fresh) {
@@ -19,6 +19,14 @@ export declare const END = "<!-- forja:end -->";
19
19
  export declare const SUPPORTED_AI: readonly ['claude', 'codex', 'gemini', 'copilot'];
20
20
  /** Onde cada IA lê as instruções nativamente. */
21
21
  export declare const INSTRUCTION_FILE: Readonly<Record<string, string>>;
22
+ /**
23
+ * Skills do projeto (SPEC-051): pastas com SKILL.md em templates/project/skills/, instaladas onde cada
24
+ * IA as procura sozinha. Codex e o padrão comum entre ferramentas leem `.agents/skills/`.
25
+ */
26
+ export declare const SKILL_TARGETS: Readonly<Record<string, string>>;
27
+ export declare function templateSkills(): string[];
28
+ /** Valida o frontmatter de um SKILL.md: devolve o problema ou null. */
29
+ export declare function skillProblem(name: string, text: string | null): string | null;
22
30
  export declare const ROLES: readonly ['orchestrator', 'product', 'sdd-architect', 'context-engineer', 'governance', 'marketing'];
23
31
  /** Hooks do Claude Code. Guardados por `command -v`: sem `forja` no PATH, a sessão abre sem erro. */
24
32
  export declare const HOOKS: Readonly<Record<string, string>>;