@polymorphism-tech/morph-spec 4.3.4 → 4.3.5

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

@@ -0,0 +1,593 @@
+# GitHub Actions Templates for MORPH-SPEC
+
+> **Framework-Level CI/CD Templates for Azure App Service & EasyPanel Deployments**
+
+## Overview
+
+This directory contains reusable GitHub Actions workflows and composite actions that enable CI/CD automation for both **blazor-azure** (Azure App Service) and **nextjs-supabase** (EasyPanel/Docker) stacks.
+
+**Key Features:**
+- ✅ Framework-level reusability across stacks
+- ✅ Handlebars v2.0 templating with helpers
+- ✅ OIDC authentication for Azure (no long-lived secrets)
+- ✅ Composite actions for shared logic
+- ✅ Stack-specific override mechanism
+
+---
+
+## 📁 Structure
+
+```
+infrastructure/github/
+├── workflows/                      # Reusable workflow templates
+│   ├── dotnet-build.yml.hbs       # .NET restore, build, test, coverage
+│   ├── docker-build-push.yml.hbs  # Docker build & push to registry
+│   ├── deploy-azure-app-service.yml.hbs  # Azure App Service deployment
+│   └── deploy-easypanel.yml.hbs   # EasyPanel deployment via webhook
+│
+└── actions/                        # Composite action templates
+    ├── docker-build-push/action.yml.hbs   # Build & push Docker image
+    ├── health-check/action.yml.hbs        # Poll health endpoint
+    └── azure-auth/action.yml.hbs          # Azure OIDC login
+```
+
+---
+
+## 🔄 Reusable Workflows vs Composite Actions
+
+| Type | Purpose | When to Use | Example |
+|------|---------|-------------|---------|
+| **Reusable Workflows** | Complete CI/CD pipeline (multiple jobs) | Build + test + deploy | `dotnet-build.yml.hbs`, `deploy-azure-app-service.yml.hbs` |
+| **Composite Actions** | Single responsibility (grouped steps) | Reusable task across workflows | `azure-auth/action.yml.hbs`, `health-check/action.yml.hbs` |
+
+### Reusable Workflows
+
+**Characteristics:**
+- Defined with `on: workflow_call`
+- Can have multiple jobs
+- Accept inputs and secrets via `with:` and `secrets: inherit`
+- Called from other workflows using `uses:` at job level
+
+**Example Usage:**
+```yaml
+jobs:
+  build:
+    uses: ./.github/workflows/dotnet-build.yml
+    with:
+      dotnet-version: '10.0'
+      run-tests: true
+    secrets: inherit
+```
+
+### Composite Actions
+
+**Characteristics:**
+- Defined with `runs: using: 'composite'`
+- Bundle related shell commands
+- Lightweight (no containerization needed)
+- Called using `uses:` at step level
+
+**Example Usage:**
+```yaml
+steps:
+  - name: Azure Login
+    uses: ./.github/actions/azure-auth
+    with:
+      client-id: ${{ secrets.AZURE_CLIENT_ID }}
+      tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+      subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+```
+
+---
+
+## 🏗️ Deployment Architectures
+
+### Blazor-Azure (Azure App Service)
+
+**Deployment Flow:**
+1. **Build:** `dotnet restore` → `dotnet build` → `dotnet test`
+2. **Publish:** `dotnet publish -c Release -o ./publish`
+3. **Infrastructure:** Deploy Bicep (App Service Plan + App Service)
+4. **Deploy:** `azure/webapps-deploy@v2` with publish folder
+5. **Health Check:** Poll `/health` endpoint
+
+**Key Characteristics:**
+- ✅ Direct .NET publish (no Docker)
+- ✅ OIDC authentication (Federated Identity)
+- ✅ Bicep IaC for infrastructure
+- ✅ App Service deployment slots for blue-green
+
+**GitHub Secrets Required:**
+- `AZURE_CLIENT_ID` - Entra ID app registration client ID
+- `AZURE_TENANT_ID` - Azure AD tenant ID
+- `AZURE_SUBSCRIPTION_ID` - Azure subscription ID
+
+**Workflows:**
+- Framework: `deploy-azure-app-service.yml.hbs`
+- Stack: `stacks/blazor-azure/.morph/templates/infrastructure/github/workflows/cd-prod.yml.hbs`
+
+### NextJS-Supabase (EasyPanel/Docker)
+
+**Deployment Flow:**
+1. **Build Backend:** `dotnet restore` → `dotnet build` → `dotnet test`
+2. **Build Frontend:** `npm ci` → `npm run build` → `npm test`
+3. **Docker:** Multi-stage build for API + Web
+4. **Push:** Docker image to GitHub Container Registry (ghcr.io)
+5. **Deploy:** Trigger EasyPanel webhook with image tag
+6. **Health Check:** Poll `/health` endpoint
+
+**Key Characteristics:**
+- ✅ Docker-based deployment
+- ✅ Multi-service (API + Web)
+- ✅ GitHub Container Registry (ghcr.io)
+- ✅ EasyPanel webhook deployment
+
+**GitHub Secrets Required:**
+- `GITHUB_TOKEN` - Auto-provided for ghcr.io
+- `EASYPANEL_WEBHOOK_URL` - EasyPanel deployment webhook
+- `EASYPANEL_API_TOKEN` - EasyPanel API authentication
+- `APP_URL` - Application URL for health checks
+
+**Workflows:**
+- Framework: `docker-build-push.yml.hbs`, `deploy-easypanel.yml.hbs`
+- Stack: `stacks/nextjs-supabase/.morph/templates/infrastructure/github/workflows/cd-prod.yml.hbs`
+
+---
+
+## 🔐 Authentication & Security
+
+### Azure OIDC (Blazor-Azure)
+
+**Setup Steps:**
+
+1. **Create Entra ID App Registration:**
+   ```bash
+   az ad app create --display-name "GitHub-Blazor-Azure-OIDC"
+   ```
+
+2. **Configure Federated Credentials:**
+   ```bash
+   az ad app federated-credential create \
+     --id <APP_ID> \
+     --parameters '{
+       "name": "github-prod",
+       "issuer": "https://token.actions.githubusercontent.com",
+       "subject": "repo:<ORG>/<REPO>:environment:production",
+       "audiences": ["api://AzureADTokenExchange"]
+     }'
+   ```
+
+3. **Assign RBAC Roles:**
+   ```bash
+   az role assignment create \
+     --assignee <APP_ID> \
+     --role "Contributor" \
+     --scope /subscriptions/<SUBSCRIPTION_ID>
+   ```
+
+4. **Configure GitHub Secrets:**
+   - `AZURE_CLIENT_ID` - App registration client ID
+   - `AZURE_TENANT_ID` - Tenant ID
+   - `AZURE_SUBSCRIPTION_ID` - Subscription ID
+
+**Workflow Usage:**
+```yaml
+- name: Azure Login (OIDC)
+  uses: azure/login@v1
+  with:
+    client-id: ${{ secrets.AZURE_CLIENT_ID }}
+    tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+    subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+```
+
+### GitHub Container Registry (NextJS-Supabase)
+
+**Setup:**
+
+1. **Enable GHCR:**
+   - No additional setup needed - `GITHUB_TOKEN` is auto-provided
+
+2. **Workflow Usage:**
+   ```yaml
+   - name: Login to GHCR
+     uses: docker/login-action@v3
+     with:
+       registry: ghcr.io
+       username: ${{ github.actor }}
+       password: ${{ secrets.GITHUB_TOKEN }}
+   ```
+
+3. **Image Naming:**
+   ```yaml
+   image: ghcr.io/${{ github.repository_owner }}/myapp:${{ github.sha }}
+   ```
+
+---
+
+## 📝 Handlebars Variables & Helpers
+
+### Auto-Injected Variables
+
+| Variable | Example | Source |
+|----------|---------|--------|
+| `{{APP_NAME}}` | `myapp` | config.json → project.name |
+| `{{DOTNET_VERSION}}` | `10.0` | config.json → dotnet.version |
+| `{{GITHUB_OWNER}}` | `myorg` | config.json → repository.owner |
+| `{{DATE}}` | `2026-02-18` | Generated at render time |
+| `{{YEAR}}` | `2026` | Generated at render time |
+
+### Handlebars Helpers
+
+| Helper | Input | Output | Use Case |
+|--------|-------|--------|----------|
+| `{{kebabCase str}}` | `MyApp` | `my-app` | Docker image names, Azure resources |
+| `{{pascalCase str}}` | `my-app` | `MyApp` | Class names (rarely needed in YAML) |
+| `{{camelCase str}}` | `my-app` | `myApp` | Variables (rarely needed in YAML) |
+
+### Escaping GitHub Actions Syntax
+
+**Problem:** GitHub Actions uses `${{ }}` syntax, which conflicts with Handlebars.
+
+**Solution:** Use `{{{{raw}}}}` blocks to preserve GitHub Actions syntax:
+
+```yaml
+# WRONG (Handlebars will interpret this)
+dotnet-version: ${{ inputs.dotnet-version }}
+
+# CORRECT (Escaped for GitHub Actions)
+dotnet-version: {{{{raw}}}}${{ inputs.dotnet-version }}{{{{/raw}}}}
+```
+
+**In Templates:**
+```handlebars
+{{#if run-tests}}
+- name: Test
+  run: dotnet test --configuration {{{{raw}}}}${{ inputs.build-configuration }}{{{{/raw}}}}
+{{/if}}
+```
+
+---
+
+## 🚀 Template Rendering Process
+
+### GitHub Actions Constraint
+
+❌ **GitHub Actions CANNOT reference parent directories**
+- Example: `uses: ../../../../framework/templates/...` ❌ NOT SUPPORTED
+
+✅ **Solution:** Render framework templates into each stack's `.github/` directory
+
+**Rendering Flow:**
+```
+framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs
+  ↓ (render with Handlebars)
+stacks/blazor-azure/.github/workflows/dotnet-build.yml
+  ↓ (commit to repo)
+GitHub Actions execution
+```
+
+### Rendering Command (Manual for Now)
+
+**Current Approach:**
+```bash
+# Manual rendering using Node.js script (future: CLI command)
+node scripts/render-github-workflows.js \
+  --stack blazor-azure \
+  --app-name myapp \
+  --dotnet-version 10.0 \
+  --output stacks/blazor-azure/.github/
+```
+
+**Future CLI Command:**
+```bash
+# Planned (not yet implemented)
+morph-spec template render github-workflows \
+  --stack blazor-azure \
+  --environment prod \
+  --output stacks/blazor-azure/.github/
+```
+
+### What Gets Committed
+
+✅ **Commit:** Rendered `.yml` files in `.github/workflows/` and `.github/actions/`
+❌ **Don't Commit:** Template sources (`.yml.hbs` files) - these stay in `.morph/templates/`
+
+**Example:**
+```
+# Committed to repo:
+.github/
+├── workflows/
+│   ├── ci-build.yml          # Rendered from template
+│   ├── cd-staging.yml        # Rendered from template
+│   └── cd-prod.yml           # Rendered from template
+└── actions/
+    └── azure-auth/
+        └── action.yml        # Rendered from template
+
+# NOT committed (template sources):
+.morph/templates/infrastructure/github/
+├── workflows/
+│   ├── ci-build.yml.hbs      # Template source
+│   └── ...
+```
+
+---
+
+## 🔀 Stack Override Mechanism
+
+Templates follow the 3-tier resolution hierarchy:
+
+1. **Project-local** (highest priority)
+   - `.morph/templates/infrastructure/github/workflows/ci-build.yml.hbs`
+   - Use for project-specific customizations
+
+2. **Stack default** (medium priority)
+   - `stacks/blazor-azure/.morph/templates/infrastructure/github/workflows/ci-build.yml.hbs`
+   - Stack-specific workflows (production, staging, CI)
+
+3. **Framework fallback** (lowest priority)
+   - `framework/templates/infrastructure/github/workflows/dotnet-build.yml.hbs`
+   - Reusable fragments called by stack workflows
+
+**Example:**
+
+Stack workflow `cd-prod.yml.hbs` **calls** framework workflow `dotnet-build.yml.hbs`:
+```yaml
+# Stack: stacks/blazor-azure/.morph/templates/.../cd-prod.yml.hbs
+jobs:
+  build:
+    uses: ./.github/workflows/dotnet-build.yml  # Framework template (rendered)
+    with:
+      dotnet-version: '{{DOTNET_VERSION}}'
+```
+
+---
+
+## 🧪 Testing & Validation
+
+### Local Testing with `act`
+
+Use [act](https://github.com/nektos/act) to test GitHub Actions locally:
+
+```bash
+# Install act
+brew install act  # macOS
+# or: choco install act  # Windows
+
+# List all workflows
+cd stacks/blazor-azure
+act -l
+
+# Dry run (validate syntax)
+act --dry-run
+
+# Run specific workflow
+act push -W .github/workflows/ci-build.yml
+
+# Run with secrets (from .secrets file)
+act push --secret-file .secrets
+```
+
+### Syntax Validation
+
+**Validate YAML syntax:**
+```bash
+# Using yamllint
+yamllint .github/workflows/*.yml
+
+# Using actionlint (GitHub Actions-specific)
+actionlint .github/workflows/*.yml
+```
+
+### Integration Testing
+
+**Test in Staging First:**
+1. Push to `staging` branch
+2. Monitor workflow execution in GitHub Actions tab
+3. Verify deployment to staging environment
+4. Test health endpoints
+5. Once validated, merge to `main` for production
+
+---
+
+## 📊 Workflow Examples
+
+### Example 1: CI Build (Blazor-Azure)
+
+**Stack Template:** `stacks/blazor-azure/.morph/templates/infrastructure/github/workflows/ci-build.yml.hbs`
+
+```yaml
+name: CI Build
+
+on:
+  pull_request:
+    branches: [main, staging]
+  push:
+    branches: [main, staging]
+
+jobs:
+  build:
+    uses: ./.github/workflows/dotnet-build.yml
+    with:
+      dotnet-version: '{{DOTNET_VERSION}}'
+      build-configuration: 'Release'
+      run-tests: true
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check vulnerable packages
+        run: dotnet list package --vulnerable --include-transitive
+```
+
+### Example 2: Production Deployment (NextJS-Supabase)
+
+**Stack Template:** `stacks/nextjs-supabase/.morph/templates/infrastructure/github/workflows/cd-prod.yml.hbs`
+
+```yaml
+name: Deploy to Production
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build-docker:
+    uses: ./.github/workflows/docker-build-push.yml
+    with:
+      registry: 'ghcr.io'
+      image-name: '{{GITHUB_OWNER}}/{{kebabCase APP_NAME}}'
+      dockerfile-path: 'Dockerfile'
+    secrets: inherit
+
+  deploy:
+    needs: build-docker
+    uses: ./.github/workflows/deploy-easypanel.yml
+    with:
+      environment: 'production'
+      image: {{{{raw}}}}${{ needs.build-docker.outputs.image-tag }}{{{{/raw}}}}
+    secrets: inherit
+```
+
+---
+
+## 🔧 Customization Guide
+
+### Creating Stack-Specific Workflows
+
+1. **Create override template:**
+   ```bash
+   mkdir -p stacks/blazor-azure/.morph/templates/infrastructure/github/workflows
+   ```
+
+2. **Copy framework template:**
+   ```bash
+   cp framework/templates/infrastructure/github/workflows/deploy-azure-app-service.yml.hbs \
+      stacks/blazor-azure/.morph/templates/infrastructure/github/workflows/
+   ```
+
+3. **Customize:**
+   - Add stack-specific jobs (e.g., blue-green deployment)
+   - Modify environment variables
+   - Add security scanning steps
+
+4. **Render:**
+   ```bash
+   # Manual rendering (future: CLI command)
+   node scripts/render-github-workflows.js --stack blazor-azure
+   ```
+
+### Adding Custom Composite Actions
+
+1. **Create action directory:**
+   ```bash
+   mkdir -p framework/templates/infrastructure/github/actions/my-action
+   ```
+
+2. **Create `action.yml.hbs`:**
+   ```yaml
+   name: 'My Custom Action'
+   description: 'Description here'
+   inputs:
+     my-input:
+       description: 'Input description'
+       required: true
+
+   runs:
+     using: 'composite'
+     steps:
+       - name: Do something
+         shell: bash
+         run: |
+           echo "Input: {{{{raw}}}}${{ inputs.my-input }}{{{{/raw}}}}"
+   ```
+
+3. **Register in REGISTRY.json:**
+   ```json
+   {
+     "id": "github-action-my-action",
+     "name": "My Custom Action",
+     "path": "infrastructure/github/actions/my-action/action.yml.hbs",
+     "location": "framework",
+     "category": "infrastructure",
+     "technology": "github-actions",
+     "engine": "handlebars"
+   }
+   ```
+
+---
+
+## 📚 Resources
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Reusable Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows)
+- [Composite Actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action)
+- [Azure Login Action](https://github.com/Azure/login)
+- [Docker Login Action](https://github.com/docker/login-action)
+- [OIDC in Azure](https://docs.microsoft.com/en-us/azure/active-directory/develop/workload-identity-federation)
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Issue 1: "uses: path is not valid"**
+```yaml
+# WRONG
+uses: ../../../../framework/templates/.../workflow.yml
+
+# CORRECT
+uses: ./.github/workflows/workflow.yml  # Rendered template
+```
+
+**Issue 2: Handlebars placeholders in rendered YAML**
+```yaml
+# Check for unreplaced placeholders
+grep -r "{{" .github/workflows/
+
+# If found, ensure rendering process completed successfully
+```
+
+**Issue 3: OIDC authentication fails**
+```
+Error: Unable to get ACTIONS_ID_TOKEN_REQUEST_TOKEN env variable
+```
+
+**Fix:** Ensure federated credentials are configured correctly in Azure AD:
+```bash
+# Verify federated credential
+az ad app federated-credential show \
+  --id <APP_ID> \
+  --federated-credential-id github-prod
+```
+
+**Issue 4: Health check fails**
+```
+curl: (7) Failed to connect to app-myapp-prod.azurewebsites.net
+```
+
+**Fix:** Add startup delay before health check:
+```yaml
+- name: Wait for app startup
+  run: sleep 30
+
+- name: Health Check
+  run: curl --retry 10 --retry-delay 5 ...
+```
+
+---
+
+## 🎯 Summary
+
+- ✅ **Framework-level reusability** across blazor-azure and nextjs-supabase stacks
+- ✅ **Handlebars v2.0 templating** with helpers (kebabCase, pascalCase, etc.)
+- ✅ **OIDC authentication** for Azure (modern, secure, no long-lived secrets)
+- ✅ **Composite actions** for shared logic (docker-build-push, health-check, azure-auth)
+- ✅ **Reusable workflows** for complete pipelines (dotnet-build, deploy-azure-app-service)
+- ✅ **Stack override mechanism** for customization (3-tier resolution)
+- ✅ **Rendered outputs committed** to `.github/` (GitHub Actions constraint)
+
+For questions or issues, see [framework/templates/README.md](../README.md) or open a GitHub issue.

package/.morph/templates/infrastructure/github/actions/azure-auth/action.yml.hbs

@@ -0,0 +1,22 @@
+name: 'Azure Authentication'
+description: 'Login to Azure using OIDC'
+inputs:
+  client-id:
+    description: 'Azure Client ID'
+    required: true
+  tenant-id:
+    description: 'Azure Tenant ID'
+    required: true
+  subscription-id:
+    description: 'Azure Subscription ID'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Azure Login (OIDC)
+      uses: azure/login@v1
+      with:
+        client-id: ${{{{ inputs.client-id }}}}
+        tenant-id: ${{{{ inputs.tenant-id }}}}
+        subscription-id: ${{{{ inputs.subscription-id }}}}

package/.morph/templates/infrastructure/github/actions/docker-build-push/action.yml.hbs

@@ -0,0 +1,45 @@
+name: 'Build & Push Docker Image'
+description: 'Build multi-stage Docker image and push to registry'
+inputs:
+  registry:
+    description: 'Docker registry URL'
+    required: true
+  image-name:
+    description: 'Docker image name'
+    required: true
+  dockerfile-path:
+    description: 'Path to Dockerfile'
+    required: false
+    default: 'Dockerfile'
+  build-context:
+    description: 'Docker build context'
+    required: false
+    default: '.'
+outputs:
+  image-tag:
+    description: 'Full image tag with registry'
+    value: ${{{{ steps.build.outputs.tags }}}}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Login to Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ${{{{ inputs.registry }}}}
+        username: ${{{{ secrets.REGISTRY_USERNAME }}}}
+        password: ${{{{ secrets.REGISTRY_PASSWORD }}}}
+
+    - name: Build and push
+      id: build
+      uses: docker/build-push-action@v5
+      with:
+        context: ${{{{ inputs.build-context }}}}
+        file: ${{{{ inputs.dockerfile-path }}}}
+        push: true
+        tags: ${{{{ inputs.registry }}}}/${{{{ inputs.image-name }}}}:${{{{ github.sha }}}}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max

package/.morph/templates/infrastructure/github/actions/health-check/action.yml.hbs

@@ -0,0 +1,27 @@
+name: 'Health Check'
+description: 'Poll health endpoint until ready'
+inputs:
+  url:
+    description: 'Health check URL'
+    required: true
+  timeout:
+    description: 'Timeout in seconds'
+    required: false
+    default: '300'
+  interval:
+    description: 'Polling interval in seconds'
+    required: false
+    default: '5'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Wait for health
+      shell: bash
+      run: |
+        RETRIES=$(($${{{{ inputs.timeout }}}} / ${{{{ inputs.interval }}}}))
+        curl --retry $RETRIES \
+             --retry-delay ${{{{ inputs.interval }}}} \
+             --retry-connrefused \
+             --fail \
+             ${{{{ inputs.url }}}}