@polymorphism-tech/morph-spec 7.4.0 → 7.6.0

package/framework/templates/docs/spec.md

@@ -1,228 +1,228 @@
-# Feature Specification: {{titleCase FEATURE_NAME}}
-
-| Field | Value |
-|-------|-------|
-| **ID** | {{FEATURE_NAME}} |
-| **Status** | Draft / In Review / Approved / In Progress / Done |
-| **Created** | {{DATE}} |
-| **Stack** | {{STACK}} |
-| **Complexity** | Low / Medium / High |
-| **Estimated Cost** | $X/month |
-| **Agents** | Core: All / Specialists: {list} |
-
----
-
-## Overview
-
-**Problem:** {What problem this feature solves}
-
-**Solution:** {High-level solution}
-
-**Success Criteria:**
-- [ ] {Criterion 1}
-- [ ] {Criterion 2}
-
----
-
-## Requirements
-
-**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}
-
-**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}
-
----
-
-## User Stories
-
-### US001: {Title}
-**As** {user type} **I want** {feature} **so that** {benefit}
-
-**Acceptance Criteria:** 1. {criterion} 2. {criterion}
-
-**Edge Cases:** {edge case}: {handling}
-
----
-
-## Technical Design
-
-### Stack
-| Component | Technology |
-|-----------|------------|
-| Frontend | {Next.js / .NET 10} |
-| Backend | .NET 10 / C# 14 |
-| Database | {Azure SQL / Cosmos DB} |
-
-### Data Model
-
-#### {EntityName}
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| {Property} | {Type} | {Constraints} |
-| CreatedAt | datetime2 | Default: GETUTCDATE() |
-
-### Contracts
-
-```csharp
-public interface I{{pascalCase FEATURE_NAME}}Service
-{
-    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
-    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
-}
-```
-
-**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.
-
-**Validation Checklist:**
-- [ ] Property names are descriptive (not generic "Data", "Value")
-- [ ] Records use correct types (Stream vs byte[], Guid vs string)
-- [ ] Response DTOs have all properties needed for UI
-- [ ] Request DTOs have implicit validations (required, nullable)
-
----
-
-## Domain Complexity
-
-**Nível:** {1 — CRUD / 2 — Business Logic / 3 — Bounded Context}
-
-**Justificativa:** {Por que este nível foi escolhido — mencionar invariants, eventos ou BCs se Nível 2+}
-
-**Padrões Aplicados:**
-- {Nível 1: Entity simples, Service CRUD, DTOs}
-- {Nível 2: AggregateRoot, Value Objects, Domain Events, CQRS}
-- {Nível 3: Bounded Context isolation, cross-BC events, Linguagem Ubíqua}
-
-**Padrões Omitidos:**
-- {ex: Bounded Contexts — sistema single-domain}
-
----
-
-## Architecture Style: Vertical Slice
-
-> Preencher SOMENTE se `config.architecture.style === "vertical-slice"`. Omitir em projetos DDD.
-
-**Architecture Style:** Vertical Slice Architecture (VSA)
-
-**Entity Fields:**
-| Field | Type | Constraints |
-|-------|------|-------------|
-| Id | Guid | PK, `Guid.CreateVersion7()` |
-| {Field} | {C# Type} | {Required / Optional / Unique} |
-| CreatedAt | DateTimeOffset | Auto |
-
-**Operations:**
-| Slice | HTTP | Route | Has Validator |
-|-------|------|-------|---------------|
-| Create{Entity} | POST | {ROUTE} | Yes |
-| GetAll{Entity}s | GET | {ROUTE} | No |
-| Get{Entity}ById | GET | {ROUTE}/{id} | Yes |
-| Update{Entity} | PUT | {ROUTE}/{id} | Yes |
-| Delete{Entity} | DELETE | {ROUTE}/{id} | Yes |
-
-**Error Types ({Entity}Errors):**
-- `{Entity}Errors.{ErrorName}()` — {description}
-
-**Validation Rules:**
-| Field | Rules |
-|-------|-------|
-| {Field} | NotEmpty(), MaxLength({N}), {etc.} |
-
----
-
-## Aggregate Blueprint (Nível 2+ apenas)
-
-> Omitir esta seção se Nível 1 (CRUD) ou se Architecture Style = Vertical Slice.
-
-### Aggregate Root: {EntityName}
-
-**Invariants:**
-- {Invariant 1 em linguagem natural}
-- {Invariant 2}
-
-**Estados e Transições:**
-```
-{Status.Draft} → Confirm() → {Status.Confirmed} → Cancel() → {Status.Cancelled}
-```
-
-**Domain Events:**
-- `{EntityName}CreatedEvent` — publicado ao criar
-- `{EntityName}StatusChangedEvent` — publicado em mudança de estado
-
-**Value Objects:**
-- `{ValueObjectName}` — {por que não é primitivo simples}
-
-**Referências Cross-Aggregate (por ID):**
-- `{OtherEntity}Id: Guid`
-
-### Linguagem Ubíqua
-
-| Termo | Definição | Código |
-|-------|-----------|--------|
-| {Termo} | {Definição do negócio} | `{ClassName.MethodName()}` |
-
----
-
-## UI/UX Design (if front-end)
-
-### Wireframes
-```
-{ASCII wireframe per screen - include states: loading, error, empty}
-```
-
-### User Flow
-1. {Step} → {System response}
-
----
-
-## Flows
-
-### {Flow Name}
-**Trigger:** {what starts this flow}
-1. {Actor} {action} → {system response}
-2. If {condition}: Path A / Else: Path B
-**End State:** {final state}
-
----
-
-## Cost Estimate
-
-| Resource | SKU | Monthly Cost | Justification |
-|----------|-----|--------------|---------------|
-| {Resource} | {SKU} | ${X} | {Why} |
-| **Total** | | **${X}/month** | |
-
----
-
-## ADRs (Architectural Decision Records)
-
-### ADR-001: {Decision Title}
-**Status:** Proposed / Accepted
-**Context:** {Why decide now}
-**Decision:** {What we chose}
-**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
-**Trade-offs:** {key trade-offs}
-
----
-
-## Security
-
-| Action | Required Policy |
-|--------|-----------------|
-| View | CanView{Feature} |
-| Create | CanManage{Feature} |
-
-## Risks
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| {Risk} | {H/M/L} | {Mitigation} |
-
-## Out of Scope
-- {Item}
-
-## Definition of Done
-- [ ] Code implemented
-- [ ] Tests >80% coverage
-- [ ] Code review approved
-- [ ] Deploy to staging
-- [ ] Recap.md generated
+# Feature Specification: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **ID** | {{FEATURE_NAME}} |
+| **Status** | Draft / In Review / Approved / In Progress / Done |
+| **Created** | {{DATE}} |
+| **Stack** | {{STACK}} |
+| **Complexity** | Low / Medium / High |
+| **Estimated Cost** | $X/month |
+| **Agents** | Core: All / Specialists: {list} |
+
+---
+
+## Overview
+
+**Problem:** {What problem this feature solves}
+
+**Solution:** {High-level solution}
+
+**Success Criteria:**
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+
+---
+
+## Requirements
+
+**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}
+
+**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}
+
+---
+
+## User Stories
+
+### US001: {Title}
+**As** {user type} **I want** {feature} **so that** {benefit}
+
+**Acceptance Criteria:** 1. {criterion} 2. {criterion}
+
+**Edge Cases:** {edge case}: {handling}
+
+---
+
+## Technical Architecture
+
+### Stack
+| Component | Technology |
+|-----------|------------|
+| Frontend | {Next.js / .NET 10} |
+| Backend | .NET 10 / C# 14 |
+| Database | {Azure SQL / Cosmos DB} |
+
+### Data Model
+
+#### {EntityName}
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK |
+| {Property} | {Type} | {Constraints} |
+| CreatedAt | datetime2 | Default: GETUTCDATE() |
+
+### Contracts
+
+```csharp
+public interface I{{pascalCase FEATURE_NAME}}Service
+{
+    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
+    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
+}
+```
+
+**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.
+
+**Validation Checklist:**
+- [ ] Property names are descriptive (not generic "Data", "Value")
+- [ ] Records use correct types (Stream vs byte[], Guid vs string)
+- [ ] Response DTOs have all properties needed for UI
+- [ ] Request DTOs have implicit validations (required, nullable)
+
+---
+
+## Domain Complexity
+
+**Nível:** {1 — CRUD / 2 — Business Logic / 3 — Bounded Context}
+
+**Justificativa:** {Por que este nível foi escolhido — mencionar invariants, eventos ou BCs se Nível 2+}
+
+**Padrões Aplicados:**
+- {Nível 1: Entity simples, Service CRUD, DTOs}
+- {Nível 2: AggregateRoot, Value Objects, Domain Events, CQRS}
+- {Nível 3: Bounded Context isolation, cross-BC events, Linguagem Ubíqua}
+
+**Padrões Omitidos:**
+- {ex: Bounded Contexts — sistema single-domain}
+
+---
+
+## Architecture Style: Vertical Slice
+
+> Preencher SOMENTE se `config.architecture.style === "vertical-slice"`. Omitir em projetos DDD.
+
+**Architecture Style:** Vertical Slice Architecture (VSA)
+
+**Entity Fields:**
+| Field | Type | Constraints |
+|-------|------|-------------|
+| Id | Guid | PK, `Guid.CreateVersion7()` |
+| {Field} | {C# Type} | {Required / Optional / Unique} |
+| CreatedAt | DateTimeOffset | Auto |
+
+**Operations:**
+| Slice | HTTP | Route | Has Validator |
+|-------|------|-------|---------------|
+| Create{Entity} | POST | {ROUTE} | Yes |
+| GetAll{Entity}s | GET | {ROUTE} | No |
+| Get{Entity}ById | GET | {ROUTE}/{id} | Yes |
+| Update{Entity} | PUT | {ROUTE}/{id} | Yes |
+| Delete{Entity} | DELETE | {ROUTE}/{id} | Yes |
+
+**Error Types ({Entity}Errors):**
+- `{Entity}Errors.{ErrorName}()` — {description}
+
+**Validation Rules:**
+| Field | Rules |
+|-------|-------|
+| {Field} | NotEmpty(), MaxLength({N}), {etc.} |
+
+---
+
+## Aggregate Blueprint (Nível 2+ apenas)
+
+> Omitir esta seção se Nível 1 (CRUD) ou se Architecture Style = Vertical Slice.
+
+### Aggregate Root: {EntityName}
+
+**Invariants:**
+- {Invariant 1 em linguagem natural}
+- {Invariant 2}
+
+**Estados e Transições:**
+```
+{Status.Draft} → Confirm() → {Status.Confirmed} → Cancel() → {Status.Cancelled}
+```
+
+**Domain Events:**
+- `{EntityName}CreatedEvent` — publicado ao criar
+- `{EntityName}StatusChangedEvent` — publicado em mudança de estado
+
+**Value Objects:**
+- `{ValueObjectName}` — {por que não é primitivo simples}
+
+**Referências Cross-Aggregate (por ID):**
+- `{OtherEntity}Id: Guid`
+
+### Linguagem Ubíqua
+
+| Termo | Definição | Código |
+|-------|-----------|--------|
+| {Termo} | {Definição do negócio} | `{ClassName.MethodName()}` |
+
+---
+
+## UI/UX Design (if front-end)
+
+### Wireframes
+```
+{ASCII wireframe per screen - include states: loading, error, empty}
+```
+
+### User Flow
+1. {Step} → {System response}
+
+---
+
+## Flows
+
+### {Flow Name}
+**Trigger:** {what starts this flow}
+1. {Actor} {action} → {system response}
+2. If {condition}: Path A / Else: Path B
+**End State:** {final state}
+
+---
+
+## Cost Estimate
+
+| Resource | SKU | Monthly Cost | Justification |
+|----------|-----|--------------|---------------|
+| {Resource} | {SKU} | ${X} | {Why} |
+| **Total** | | **${X}/month** | |
+
+---
+
+## ADRs (Architectural Decision Records)
+
+### ADR-001: {Decision Title}
+**Status:** Proposed / Accepted
+**Context:** {Why decide now}
+**Decision:** {What we chose}
+**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
+**Trade-offs:** {key trade-offs}
+
+---
+
+## Security
+
+| Action | Required Policy |
+|--------|-----------------|
+| View | CanView{Feature} |
+| Create | CanManage{Feature} |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {Risk} | {H/M/L} | {Mitigation} |
+
+## Out of Scope
+- {Item}
+
+## Definition of Done
+- [ ] Code implemented
+- [ ] Tests >80% coverage
+- [ ] Code review approved
+- [ ] Deploy to staging
+- [ ] Recap.md generated

package/framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs

@@ -1,4 +1,4 @@
-# Multi-stage Next.js production build for EasyPanel
+# Multi-stage Next.js production build for Coolify
 # Stage 1: Dependencies
 FROM node:20-alpine AS deps
 RUN apk add --no-cache libc6-compat

package/framework/templates/infrastructure/docker/coolify.template.json

@@ -0,0 +1,49 @@
+{
+  "name": "{{kebabCase FEATURE_NAME}}",
+  "provider": "coolify",
+  "access": {
+    "method": "ssh",
+    "note": "No MCP/CLI exists for Coolify — replace sshHost with the real SSH alias for the target VPS. The API is reached only from inside the VPS, at apiBaseUrl.",
+    "sshHost": "REPLACE_WITH_VPS_SSH_ALIAS",
+    "apiBaseUrl": "http://localhost:8000/api/v1",
+    "tokenPath": "~/.coolify-token"
+  },
+  "application": {
+    "uuid": "REPLACE_WITH_COOLIFY_APPLICATION_UUID",
+    "projectUuid": "REPLACE_WITH_COOLIFY_PROJECT_UUID",
+    "serverUuid": "REPLACE_WITH_COOLIFY_SERVER_UUID"
+  },
+  "source": {
+    "type": "github",
+    "owner": "{{GITHUB_OWNER}}",
+    "repo": "{{GITHUB_REPO}}",
+    "branch": "main",
+    "autoDeploy": true
+  },
+  "build": {
+    "type": "dockerfile",
+    "dockerfile": "Dockerfile"
+  },
+  "deploy": {
+    "replicas": 1,
+    "zeroDowntime": true
+  },
+  "env": [
+    {
+      "key": "NODE_ENV",
+      "value": "production"
+    },
+    {
+      "key": "DATABASE_URL",
+      "value": "${DATABASE_URL}"
+    }
+  ],
+  "domains": [
+    {
+      "host": "{{kebabCase FEATURE_NAME}}.example.com",
+      "port": 3000,
+      "https": true
+    }
+  ],
+  "deployCommand": "ssh REPLACE_WITH_VPS_SSH_ALIAS 'T=$(cat ~/.coolify-token); curl -s -X GET -H \"Authorization: Bearer $T\" \"http://localhost:8000/api/v1/deploy?uuid=REPLACE_WITH_COOLIFY_APPLICATION_UUID\"'"
+}

package/framework/templates/infrastructure/github/README.md

@@ -1,16 +1,16 @@
 # GitHub Actions Templates for MORPH-SPEC
 
-> **Framework-Level CI/CD Templates for EasyPanel/Docker Deployments**
+> **Framework-Level CI/CD Templates for Coolify/Docker Deployments**
 
 ## Overview
 
-Reusable GitHub Actions workflows and composite actions for the **nextjs-neon** stack (EasyPanel/Docker deployment).
+Reusable GitHub Actions workflows and composite actions for the **nextjs-neon** stack (Coolify/Docker deployment).
 
 **Key Features:**
 - Handlebars v2.0 templating with helpers
 - Composite actions for shared logic
 - Docker multi-stage builds (.NET API + Next.js Web)
-- EasyPanel webhook deployment
+- Coolify deployment via SSH (no MCP/CLI exists — the Coolify API is not publicly exposed, so the runner SSHes into the VPS to trigger it)
 
 ---
 
@@ -21,7 +21,7 @@ infrastructure/github/
 ├── workflows/
 │   ├── dotnet-build.yml.hbs       # .NET restore, build, test, coverage
 │   ├── docker-build-push.yml.hbs  # Docker build & push to registry
-│   └── deploy-easypanel.yml.hbs   # EasyPanel deployment via webhook
+│   └── deploy-coolify.yml.hbs     # Coolify deployment via SSH
 │
 └── actions/
     ├── docker-build-push/action.yml.hbs   # Build & push Docker image
@@ -38,8 +38,8 @@ infrastructure/github/
 - Multi-stage Docker build
 - Push to container registry (GHCR or Docker Hub)
 
-### Deploy EasyPanel (`deploy-easypanel.yml.hbs`)
-- Triggers EasyPanel webhook after Docker push
+### Deploy Coolify (`deploy-coolify.yml.hbs`)
+- SSHes into the VPS and calls the local Coolify API (`localhost:8000/api/v1/deploy?uuid=...`) after Docker push
 - Runs health check after deployment
 - Supports staging + production environments
 

package/framework/templates/infrastructure/github/workflows/deploy-coolify.yml.hbs

@@ -0,0 +1,33 @@
+name: Deploy to Coolify
+
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      image:
+        required: true
+        type: string
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{{{ inputs.environment }}}}
+    steps:
+      - name: Configure SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{{{ secrets.COOLIFY_SSH_KEY }}}}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan -H ${{{{ secrets.COOLIFY_SSH_HOST }}}} >> ~/.ssh/known_hosts
+
+      - name: Trigger Coolify Deploy (via SSH — the Coolify API is not publicly exposed)
+        run: |
+          ssh -i ~/.ssh/id_ed25519 ${{{{ secrets.COOLIFY_SSH_USER }}}}@${{{{ secrets.COOLIFY_SSH_HOST }}}} \
+            'T=$(cat ~/.coolify-token); curl -s -X GET -H "Authorization: Bearer $T" "http://localhost:8000/api/v1/deploy?uuid=${{{{ secrets.COOLIFY_APPLICATION_UUID }}}}"'
+
+      - name: Health Check
+        run: |
+          sleep 30  # Wait for deployment
+          curl --retry 10 --retry-delay 5 --retry-connrefused ${{{{ secrets.APP_URL }}}}/health