@polymorphism-tech/morph-spec 4.6.0 → 4.7.1

package/.morph/framework/standards/infrastructure/azure/services/storage.md

@@ -1,407 +0,0 @@
-# Azure Storage Services Standard
-
-> **Scope:** blazor-azure
-> **Layer:** 2 (on keyword)
-> **Keywords:** azure storage, blob, queue, table, file storage
-> **Load When:** azure storage keywords detected
-
-Azure Storage services patterns for Blob, Queue, Table, and File storage.
-
----
-
-## Overview
-
-Azure Storage provides:
-- **Blob Storage**: Object storage for unstructured data (files, images, videos)
-- **Queue Storage**: Message queuing for async processing
-- **Table Storage**: NoSQL key-value store
-- **File Storage**: SMB file shares
-
-**Stack:** .NET 10 + Blazor Server
-
----
-
-## Core Principles
-
-1. **Managed Identity**: Use Managed Identity over connection strings
-2. **SAS Tokens**: Use SAS for temporary access delegation
-3. **Retry Policies**: Configure exponential backoff for transient failures
-4. **Lifecycle Management**: Auto-delete old blobs with lifecycle policies
-5. **Cost Optimization**: Use appropriate storage tiers (Hot/Cool/Archive)
-
----
-
-## Installation
-
-```bash
-dotnet add package Azure.Storage.Blobs
-dotnet add package Azure.Storage.Queues
-dotnet add package Azure.Identity
-```
-
----
-
-## Blob Storage
-
-### DI Configuration
-
-```csharp
-// Program.cs
-using Azure.Identity;
-using Azure.Storage.Blobs;
-
-builder.Services.AddSingleton(sp =>
-{
-    var blobServiceUri = new Uri(builder.Configuration["AzureStorage:BlobServiceUri"]!);
-    return new BlobServiceClient(blobServiceUri, new DefaultAzureCredential());
-});
-```
-
-### Upload Blob
-
-```csharp
-public class FileUploadService
-{
-    private readonly BlobServiceClient _blobServiceClient;
-
-    public FileUploadService(BlobServiceClient blobServiceClient)
-    {
-        _blobServiceClient = blobServiceClient;
-    }
-
-    public async Task<string> UploadFileAsync(Stream fileStream, string fileName, string containerName)
-    {
-        var containerClient = _blobServiceClient.GetBlobContainerClient(containerName);
-        await containerClient.CreateIfNotExistsAsync();
-
-        var blobClient = containerClient.GetBlobClient(fileName);
-
-        await blobClient.UploadAsync(fileStream, overwrite: true);
-
-        return blobClient.Uri.ToString();
-    }
-}
-```
-
-### Download Blob
-
-```csharp
-public async Task<Stream> DownloadFileAsync(string fileName, string containerName)
-{
-    var containerClient = _blobServiceClient.GetBlobContainerClient(containerName);
-    var blobClient = containerClient.GetBlobClient(fileName);
-
-    var response = await blobClient.DownloadAsync();
-    return response.Value.Content;
-}
-```
-
-### Generate SAS Token
-
-```csharp
-using Azure.Storage.Sas;
-
-public string GenerateSasUri(string containerName, string blobName, TimeSpan validity)
-{
-    var containerClient = _blobServiceClient.GetBlobContainerClient(containerName);
-    var blobClient = containerClient.GetBlobClient(blobName);
-
-    var sasBuilder = new BlobSasBuilder
-    {
-        BlobContainerName = containerName,
-        BlobName = blobName,
-        Resource = "b", // Blob
-        StartsOn = DateTimeOffset.UtcNow,
-        ExpiresOn = DateTimeOffset.UtcNow.Add(validity)
-    };
-
-    sasBuilder.SetPermissions(BlobSasPermissions.Read);
-
-    var sasUri = blobClient.GenerateSasUri(sasBuilder);
-    return sasUri.ToString();
-}
-```
-
----
-
-## Queue Storage
-
-### DI Configuration
-
-```csharp
-// Program.cs
-builder.Services.AddSingleton(sp =>
-{
-    var queueServiceUri = new Uri(builder.Configuration["AzureStorage:QueueServiceUri"]!);
-    return new QueueServiceClient(queueServiceUri, new DefaultAzureCredential());
-});
-```
-
-### Send Message
-
-```csharp
-public class QueueService
-{
-    private readonly QueueServiceClient _queueServiceClient;
-
-    public QueueService(QueueServiceClient queueServiceClient)
-    {
-        _queueServiceClient = queueServiceClient;
-    }
-
-    public async Task SendMessageAsync(string queueName, string message)
-    {
-        var queueClient = _queueServiceClient.GetQueueClient(queueName);
-        await queueClient.CreateIfNotExistsAsync();
-
-        await queueClient.SendMessageAsync(message);
-    }
-
-    public async Task SendMessageWithDelayAsync(string queueName, string message, TimeSpan delay)
-    {
-        var queueClient = _queueServiceClient.GetQueueClient(queueName);
-        await queueClient.CreateIfNotExistsAsync();
-
-        await queueClient.SendMessageAsync(message, visibilityTimeout: delay);
-    }
-}
-```
-
-### Process Messages
-
-```csharp
-using Azure.Storage.Queues.Models;
-
-public async Task ProcessMessagesAsync(string queueName, CancellationToken cancellationToken)
-{
-    var queueClient = _queueServiceClient.GetQueueClient(queueName);
-
-    while (!cancellationToken.IsCancellationRequested)
-    {
-        QueueMessage[] messages = await queueClient.ReceiveMessagesAsync(maxMessages: 32);
-
-        foreach (var message in messages)
-        {
-            try
-            {
-                // Process message
-                await ProcessMessageAsync(message.MessageText);
-
-                // Delete message after successful processing
-                await queueClient.DeleteMessageAsync(message.MessageId, message.PopReceipt);
-            }
-            catch (Exception ex)
-            {
-                // Log error, message will become visible again after timeout
-                _logger.LogError(ex, "Failed to process message {MessageId}", message.MessageId);
-            }
-        }
-
-        if (messages.Length == 0)
-        {
-            await Task.Delay(TimeSpan.FromSeconds(5), cancellationToken);
-        }
-    }
-}
-```
-
----
-
-## Table Storage
-
-### DI Configuration
-
-```csharp
-dotnet add package Azure.Data.Tables
-
-// Program.cs
-builder.Services.AddSingleton(sp =>
-{
-    var tableServiceUri = new Uri(builder.Configuration["AzureStorage:TableServiceUri"]!);
-    return new TableServiceClient(tableServiceUri, new DefaultAzureCredential());
-});
-```
-
-### Entity Model
-
-```csharp
-using Azure;
-using Azure.Data.Tables;
-
-public class ProductEntity : ITableEntity
-{
-    public string PartitionKey { get; set; } = default!; // Category
-    public string RowKey { get; set; } = default!;       // ProductId
-    public DateTimeOffset? Timestamp { get; set; }
-    public ETag ETag { get; set; }
-
-    public string Name { get; set; } = string.Empty;
-    public decimal Price { get; set; }
-    public int Stock { get; set; }
-}
-```
-
-### CRUD Operations
-
-```csharp
-public class ProductTableService
-{
-    private readonly TableClient _tableClient;
-
-    public ProductTableService(TableServiceClient tableServiceClient)
-    {
-        _tableClient = tableServiceClient.GetTableClient("products");
-        _tableClient.CreateIfNotExists();
-    }
-
-    public async Task AddProductAsync(ProductEntity product)
-    {
-        await _tableClient.AddEntityAsync(product);
-    }
-
-    public async Task<ProductEntity?> GetProductAsync(string category, string productId)
-    {
-        try
-        {
-            return await _tableClient.GetEntityAsync<ProductEntity>(category, productId);
-        }
-        catch (RequestFailedException ex) when (ex.Status == 404)
-        {
-            return null;
-        }
-    }
-
-    public async Task<List<ProductEntity>> QueryProductsAsync(string category)
-    {
-        var query = _tableClient.QueryAsync<ProductEntity>(p => p.PartitionKey == category);
-
-        var results = new List<ProductEntity>();
-        await foreach (var product in query)
-        {
-            results.Add(product);
-        }
-
-        return results;
-    }
-
-    public async Task UpdateProductAsync(ProductEntity product)
-    {
-        await _tableClient.UpdateEntityAsync(product, ETag.All, TableUpdateMode.Replace);
-    }
-
-    public async Task DeleteProductAsync(string category, string productId)
-    {
-        await _tableClient.DeleteEntityAsync(category, productId);
-    }
-}
-```
-
----
-
-## Best Practices
-
-### Retry Policy
-
-```csharp
-using Azure.Core;
-
-var options = new BlobClientOptions
-{
-    Retry =
-    {
-        Mode = RetryMode.Exponential,
-        MaxRetries = 3,
-        Delay = TimeSpan.FromSeconds(2),
-        MaxDelay = TimeSpan.FromSeconds(10)
-    }
-};
-
-var blobServiceClient = new BlobServiceClient(blobServiceUri, credential, options);
-```
-
-### Blob Metadata
-
-```csharp
-var metadata = new Dictionary<string, string>
-{
-    { "uploadedBy", userId },
-    { "fileType", "invoice" },
-    { "department", "finance" }
-};
-
-await blobClient.UploadAsync(stream, metadata: metadata);
-
-// Retrieve metadata
-var properties = await blobClient.GetPropertiesAsync();
-var uploadedBy = properties.Value.Metadata["uploadedBy"];
-```
-
-### Lifecycle Management
-
-```json
-// Configure in Azure Portal or via Bicep
-{
-  "rules": [
-    {
-      "name": "deleteOldBackups",
-      "enabled": true,
-      "type": "Lifecycle",
-      "definition": {
-        "filters": {
-          "blobTypes": ["blockBlob"],
-          "prefixMatch": ["backups/"]
-        },
-        "actions": {
-          "baseBlob": {
-            "delete": {
-              "daysAfterModificationGreaterThan": 30
-            }
-          }
-        }
-      }
-    }
-  ]
-}
-```
-
----
-
-## Bicep Configuration
-
-```bicep
-resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = {
-  name: storageAccountName
-  location: location
-  sku: {
-    name: 'Standard_LRS'
-  }
-  kind: 'StorageV2'
-  properties: {
-    allowBlobPublicAccess: false
-    minimumTlsVersion: 'TLS1_2'
-    supportsHttpsTrafficOnly: true
-  }
-}
-
-// Grant Container App Blob access
-resource blobRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
-  scope: storageAccount
-  name: guid(storageAccount.id, principalId, 'Storage Blob Data Contributor')
-  properties: {
-    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'ba92f5b4-2d11-453d-a403-e96b0029c9fe')
-    principalId: principalId
-  }
-}
-```
-
----
-
-## References
-
-- [Azure Blob Storage](https://learn.microsoft.com/azure/storage/blobs/)
-- [Azure Queue Storage](https://learn.microsoft.com/azure/storage/queues/)
-- [Azure Table Storage](https://learn.microsoft.com/azure/storage/tables/)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/infrastructure/docker/easypanel-deploy.md

@@ -1,196 +0,0 @@
-# EasyPanel Deployment Standard
-
-> **Scope:** nextjs-supabase
-> **Layer:** 2 (on keyword)
-> **Keywords:** easypanel, docker, deploy, deployment, container
-> **Load When:** easypanel or docker deployment keywords detected
-
-Stack: Next.js 15 + Supabase + .NET Backend
-
-## Core Rules
-
-- ALWAYS use multi-stage Docker builds for minimal image size
-- ALWAYS configure health checks for zero-downtime deploys
-- NEVER hardcode secrets in Dockerfiles -- use EasyPanel environment variables
-- ALWAYS use `.dockerignore` to exclude node_modules, .git, .env files
-- SSL is automatic via Let's Encrypt -- no manual certificate management
-
-## .NET 10 Dockerfile
-
-```dockerfile
-FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
-WORKDIR /src
-COPY *.csproj .
-RUN dotnet restore
-COPY . .
-RUN dotnet publish -c Release -o /app/publish --no-restore
-
-FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
-WORKDIR /app
-RUN adduser --disabled-password --gecos "" appuser
-USER appuser
-COPY --from=build /app/publish .
-ENV ASPNETCORE_URLS=http://+:8080
-EXPOSE 8080
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD curl -f http://localhost:8080/health || exit 1
-ENTRYPOINT ["dotnet", "MyApp.Api.dll"]
-```
-
-## Next.js Standalone Dockerfile
-
-```dockerfile
-FROM node:22-alpine AS base
-
-FROM base AS builder
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci
-COPY . .
-ENV NEXT_TELEMETRY_DISABLED=1
-RUN npm run build
-
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1
-RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
-COPY --from=builder /app/public ./public
-COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
-COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
-USER nextjs
-EXPOSE 3000
-ENV PORT=3000 HOSTNAME="0.0.0.0"
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
-  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
-CMD ["node", "server.js"]
-```
-
-Required: `output: "standalone"` in `next.config.ts`.
-
-## .dockerignore
-
-```
-node_modules
-.next
-.git
-.env*
-*.md
-.vscode
-coverage
-test
-__tests__
-```
-
-## EasyPanel Service Config
-
-| Setting | .NET Backend | Next.js Frontend |
-|---------|-------------|-----------------|
-| Source | GitHub | GitHub |
-| Build method | Dockerfile | Dockerfile |
-| Dockerfile path | `./backend/Dockerfile` | `./frontend/Dockerfile` |
-| Port | 8080 | 3000 |
-| Domain | api.example.com | app.example.com |
-
-### GitHub Integration
-
-1. Generate GitHub PAT with `repo` scope
-2. EasyPanel: Settings > GitHub > Add token
-3. Select repository and branch
-4. Enable "Auto Deploy" for webhook-triggered deploys
-
-### Domain and SSL
-
-DNS setup (CNAME to EasyPanel server):
-```
-app.example.com  CNAME  your-server.easypanel.host
-api.example.com  CNAME  your-server.easypanel.host
-```
-
-SSL via Let's Encrypt is automatic. Force HTTPS enabled by default.
-
-## Environment Variables
-
-### .NET Backend
-
-```env
-ASPNETCORE_ENVIRONMENT=Production
-ASPNETCORE_URLS=http://+:8080
-ConnectionStrings__DefaultConnection=Host=...;Database=...;Username=...;Password=...
-Supabase__Url=https://xxx.supabase.co
-Supabase__ServiceRoleKey=eyJ...
-Supabase__JwtSecret=your-jwt-secret
-```
-
-### Next.js Frontend
-
-```env
-NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJ...
-NEXT_PUBLIC_API_URL=https://api.example.com
-```
-
-## Health Check Endpoints
-
-```csharp
-// .NET: Program.cs
-builder.Services.AddHealthChecks()
-    .AddNpgSql(connectionString, name: "database");
-app.MapHealthChecks("/health");
-```
-
-```ts
-// Next.js: app/api/health/route.ts
-export async function GET() {
-  return Response.json({ status: "healthy", timestamp: new Date().toISOString() });
-}
-```
-
-## Zero-Downtime Deploys
-
-EasyPanel uses Docker HEALTHCHECK to determine container readiness:
-
-1. New container starts alongside old container
-2. Health check passes after start-period + retries
-3. Traffic shifts to new container
-4. Old container stopped
-
-| HEALTHCHECK Param | Value | Purpose |
-|-------------------|-------|---------|
-| `--interval` | 30s | Time between checks |
-| `--timeout` | 5s | Max response wait |
-| `--start-period` | 10s | Startup grace period |
-| `--retries` | 3 | Failures before unhealthy |
-
-## Monitoring
-
-- **Logs**: Real-time in EasyPanel UI
-- **Metrics**: CPU, memory, network via dashboard
-- **Restart**: Auto-restart on crash (default)
-
-Structured logging:
-
-```csharp
-// .NET: Serilog with JSON output
-builder.Host.UseSerilog((ctx, cfg) => cfg
-    .ReadFrom.Configuration(ctx.Configuration)
-    .WriteTo.Console(new JsonFormatter()));
-```
-
-```ts
-// Next.js: pino
-import pino from "pino";
-const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
-```
-
-## Deployment Checklist
-
-| Step | Action |
-|------|--------|
-| 1 | Verify `output: "standalone"` in next.config.ts |
-| 2 | Test Docker build locally |
-| 3 | Test health endpoint |
-| 4 | Configure env vars in EasyPanel |
-| 5 | Set up custom domain + DNS |
-| 6 | Verify SSL certificate |
-| 7 | Enable auto-deploy from GitHub |
-| 8 | Push to main, verify deployment |