npm - @polymorphism-tech/morph-spec - Versions diffs - 4.12.0 → 4.13.0 - Mend

@polymorphism-tech/morph-spec 4.12.0 → 4.13.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 (314) hide show

package/framework/standards/infrastructure/azure/services/storage.md DELETED Viewed

@@ -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/framework/standards/infrastructure/vercel/vercel-database.md DELETED Viewed

@@ -1,106 +0,0 @@
-# Vercel Deployment — Database Standard
-> **Scope:** nextjs-vercel
-> **Layer:** 1 (always-on for Vercel-deployed Next.js)
-> **Keywords:** vercel, neon, planetscale, serverless database, serverless postgres, deploy nextjs
-> **Load When:** deployment target is Vercel with Next.js stack
----
-## Rule: Vercel Requires a Serverless Database
-**NEVER** use a traditional long-lived database connection pool (PostgreSQL TCP, MySQL TCP) with Vercel.
-Vercel functions are ephemeral and stateless — each invocation may spawn a fresh process.
-A persistent connection pool (e.g., EF Core + plain Npgsql TCP) will exhaust database connection limits within minutes under moderate load.
-**ALWAYS** use a **serverless-compatible** database when deploying to Vercel.
----
-## Approved Serverless Databases
-| Provider | Type | Connection mode | Notes |
-|----------|------|-----------------|-------|
-| **Neon** | PostgreSQL (serverless) | HTTP (`@neondatabase/serverless`) or pooled TCP via PgBouncer | First choice for SQL |
-| **PlanetScale** | MySQL-compatible (serverless) | HTTP driver (`@planetscale/database`) | Good for MySQL ecosystems |
-| **Supabase** | PostgreSQL + PgBouncer | Pooled TCP (transaction mode) or REST | Full BaaS option |
-| **Turso** | SQLite (distributed) | HTTP (`@libsql/client`) | Lightweight, edge-friendly |
----
-## Implementation: Neon (Recommended)
-```ts
-// lib/db.ts
-import { neon } from '@neondatabase/serverless';
-const sql = neon(process.env.DATABASE_URL!);
-export default sql;
-```
-```ts
-// Example: API Route (app/api/items/route.ts)
-import sql from '@/lib/db';
-export async function GET() {
-  const items = await sql`SELECT * FROM items LIMIT 50`;
-  return Response.json(items);
-}
-```
-### Environment variable
-```
-DATABASE_URL=postgresql://user:pass@ep-xxx.neon.tech/dbname?sslmode=require
-```
----
-## Implementation: Supabase + PgBouncer (Transaction Mode)
-Use the **port 6543** connection string (PgBouncer, transaction pooling):
-```
-DATABASE_URL=postgresql://user:pass@db.xxx.supabase.co:6543/postgres?pgbouncer=true&connection_limit=1
-```
-If using an ORM (Prisma/Drizzle), set `connection_limit=1` to avoid pool saturation.
----
-## Anti-patterns — NEVER use with Vercel
-```ts
-// WRONG: plain Npgsql/pg pool without serverless adapter
-import { Pool } from 'pg';
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-// → Leaks connections on every cold start
-// WRONG: EF Core (dotnet) TCP pool behind a Vercel-deployed Next.js API route
-// → Not applicable (EF Core is .NET), but calling a .NET API that pools
-//   connections is fine as long as the .NET side runs on a persistent server
-```
----
-## Decision Tree: Choose Your DB Tier
-```
-Deploying to Vercel?
-  └── YES → Use serverless DB
-        ├── Need SQL + PostGIS/pgvector? → Neon
-        ├── Need full BaaS (auth, storage, RLS)? → Supabase
-        ├── MySQL ecosystem? → PlanetScale
-        └── Edge-only, lightweight? → Turso
-  └── NO (EasyPanel, Railway, Render, Azure Container Apps)
-        └── Any PostgreSQL with connection pool is fine
-```
----
-## Validator Check (design phase)
-During `phase-design`, the standards agent must verify:
-- `config.deployment.target === 'vercel'` → enforce serverless DB selection
-- If `database.provider` is missing or is `postgresql-tcp`, flag as **BLOCKING** issue
-- Add to `decisions.md`: "Database must be serverless-compatible (Vercel constraint)"

package/framework/standards/integration/api/graphql.md DELETED Viewed

@@ -1,91 +0,0 @@
-# Integration Standard: GraphQL
-## When to Use GraphQL
-✅ Client needs fine-grained field selection (mobile apps, different clients)
-✅ Complex nested resource relationships (avoid N+1 with DataLoader)
-✅ Real-time subscriptions alongside queries
-❌ Simple CRUD APIs (REST is simpler)
-❌ File upload as primary use case (use REST for uploads)
-❌ When caching is critical (GraphQL caching is harder)
-## Setup (Hot Chocolate)
-```xml
-<PackageReference Include="HotChocolate.AspNetCore" Version="14.*" />
-<PackageReference Include="HotChocolate.Data.EntityFramework" Version="14.*" />
-```
-```csharp
-builder.Services
-    .AddGraphQLServer()
-    .AddQueryType<QueryType>()
-    .AddMutationType<MutationType>()
-    .AddSubscriptionType<SubscriptionType>()
-    .AddProjections()
-    .AddFiltering()
-    .AddSorting()
-    .AddAuthorization();
-app.MapGraphQL("/graphql");
-```
-## Query Type
-```csharp
-[QueryType]
-public class QueryType
-{
-    [UseProjection]
-    [UseFiltering]
-    [UseSorting]
-    [UsePaging]
-    public IQueryable<Order> GetOrders([Service] AppDbContext ctx) => ctx.Orders;
-    public async Task<Order?> GetOrder(Guid id, [Service] AppDbContext ctx)
-        => await ctx.Orders.FindAsync(id);
-}
-```
-## Mutation Type
-```csharp
-[MutationType]
-public class MutationType
-{
-    public async Task<CreateOrderPayload> CreateOrder(
-        CreateOrderInput input,
-        [Service] ISender sender)
-    {
-        var result = await sender.Send(new CreateOrderCommand(input.UserId, input.Items));
-        return new CreateOrderPayload(result.OrderId);
-    }
-}
-public record CreateOrderInput(Guid UserId, List<OrderItemInput> Items);
-public record CreateOrderPayload(Guid OrderId);
-```
-## DataLoader (N+1 Prevention)
-```csharp
-public class UserDataLoader : BatchDataLoader<Guid, User>
-{
-    protected override async Task<IReadOnlyDictionary<Guid, User>> LoadBatchAsync(
-        IReadOnlyList<Guid> keys, CancellationToken ct)
-    {
-        return await _context.Users
-            .Where(u => keys.Contains(u.Id))
-            .ToDictionaryAsync(u => u.Id, ct);
-    }
-}
-// Use in resolver
-public async Task<User?> GetUser([Parent] Order order, UserDataLoader loader)
-    => await loader.LoadAsync(order.UserId);
-```
-## Security
-- Apply `[Authorize]` on mutations and sensitive queries
-- Disable introspection in production
-- Depth limiting: max 5 levels
-- Complexity limiting: max 1000 nodes per query
-```csharp
-.AddMaxExecutionDepthRule(5)
-.ModifyRequestOptions(opts => opts.MaxAllowedRequestSize = 1_000_000)
-```

package/framework/standards/integration/api/grpc.md DELETED Viewed

@@ -1,114 +0,0 @@
-# Integration Standard: gRPC
-## When to Use gRPC
-✅ Internal service-to-service communication (high performance)
-✅ Streaming (server-streaming for real-time data, client-streaming for uploads)
-✅ Multi-language microservices (proto contracts shared across .NET, Go, Python)
-❌ Browser-to-server (use gRPC-Web or REST instead)
-❌ Debugging priority (binary format is harder to inspect than JSON)
-## Setup
-```xml
-<PackageReference Include="Grpc.AspNetCore" Version="2.*" />
-```
-```csharp
-// Program.cs
-builder.Services.AddGrpc(opts =>
-{
-    opts.EnableDetailedErrors = builder.Environment.IsDevelopment();
-    opts.MaxReceiveMessageSize = 4 * 1024 * 1024; // 4 MB
-});
-app.MapGrpcService<OrdersService>();
-```
-## Proto Definition
-```protobuf
-syntax = "proto3";
-option csharp_namespace = "MyApp.Grpc";
-service Orders {
-  rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
-  rpc GetOrder(GetOrderRequest) returns (OrderResponse);
-  rpc StreamOrders(StreamOrdersRequest) returns (stream OrderResponse);
-}
-message CreateOrderRequest {
-  string user_id = 1;
-  repeated OrderItem items = 2;
-}
-message CreateOrderResponse {
-  string order_id = 1;
-  double total = 2;
-}
-```
-## Service Implementation
-```csharp
-public class OrdersService : Orders.OrdersBase
-{
-    public override async Task<CreateOrderResponse> CreateOrder(
-        CreateOrderRequest request, ServerCallContext context)
-    {
-        var cmd = new CreateOrderCommand(
-            Guid.Parse(request.UserId),
-            request.Items.Select(i => new OrderItem(i.ProductId, i.Quantity)).ToList());
-        var result = await _sender.Send(cmd, context.CancellationToken);
-        return new CreateOrderResponse
-        {
-            OrderId = result.OrderId.ToString(),
-            Total = (double)result.Total
-        };
-    }
-    public override async Task StreamOrders(
-        StreamOrdersRequest request,
-        IServerStreamWriter<OrderResponse> responseStream,
-        ServerCallContext context)
-    {
-        await foreach (var order in _service.GetOrderStreamAsync(context.CancellationToken))
-        {
-            await responseStream.WriteAsync(MapToResponse(order), context.CancellationToken);
-            if (context.CancellationToken.IsCancellationRequested) break;
-        }
-    }
-}
-```
-## Client Setup
-```csharp
-// Program.cs (client service)
-builder.Services.AddGrpcClient<Orders.OrdersClient>(opts =>
-{
-    opts.Address = new Uri(config["Services:OrdersUrl"]);
-})
-.ConfigureChannel(opts =>
-{
-    opts.HttpHandler = new SocketsHttpHandler
-    {
-        PooledConnectionIdleTimeout = Timeout.InfiniteTimeSpan,
-        KeepAlivePingDelay = TimeSpan.FromSeconds(60),
-        KeepAlivePingTimeout = TimeSpan.FromSeconds(30)
-    };
-});
-```
-## Error Handling
-```csharp
-// Map exceptions to gRPC status codes
-try
-{
-    return await _service.ProcessAsync(request.Id);
-}
-catch (NotFoundException)
-{
-    throw new RpcException(new Status(StatusCode.NotFound, "Order not found"));
-}
-catch (ValidationException ex)
-{
-    throw new RpcException(new Status(StatusCode.InvalidArgument, ex.Message));
-}
-```