npm - @polymorphism-tech/morph-spec - Versions diffs - 4.6.0 → 4.7.1 - Mend

@polymorphism-tech/morph-spec 4.6.0 → 4.7.1

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 (239) hide show

package/.morph/framework/templates/infrastructure/github/README.md DELETED Viewed

@@ -1,593 +0,0 @@
-# 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/framework/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/framework/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/framework/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/framework/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/framework/templates/infrastructure/github/workflows/ci-build.yml.hbs`
-   - Use for project-specific customizations
-2. **Stack default** (medium priority)
-   - `stacks/blazor-azure/.morph/framework/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/framework/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/framework/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/framework/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/framework/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/framework/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/framework/templates/infrastructure/github/actions/azure-auth/action.yml.hbs DELETED Viewed

@@ -1,22 +0,0 @@
-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/framework/templates/infrastructure/github/actions/docker-build-push/action.yml.hbs DELETED Viewed

@@ -1,45 +0,0 @@
-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/framework/templates/infrastructure/github/actions/health-check/action.yml.hbs DELETED Viewed

@@ -1,27 +0,0 @@
-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 }}}}