@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/aws-serverless.md

@@ -0,0 +1,323 @@
+---
+name: aws-serverless
+description: "Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start optimization."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# AWS Serverless
+
+## Patterns
+
+### Lambda Handler Pattern
+
+Proper Lambda function structure with error handling
+
+**When to use**: ['Any Lambda function implementation', 'API handlers, event processors, scheduled tasks']
+
+```python
+```javascript
+// Node.js Lambda Handler
+// handler.js
+
+// Initialize outside handler (reused across invocations)
+const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
+const { DynamoDBDocumentClient, GetCommand } = require('@aws-sdk/lib-dynamodb');
+
+const client = new DynamoDBClient({});
+const docClient = DynamoDBDocumentClient.from(client);
+
+// Handler function
+exports.handler = async (event, context) => {
+  // Optional: Don't wait for event loop to clear (Node.js)
+  context.callbackWaitsForEmptyEventLoop = false;
+
+  try {
+    // Parse input based on event source
+    const body = typeof event.body === 'string'
+      ? JSON.parse(event.body)
+      : event.body;
+
+    // Business logic
+    const result = await processRequest(body);
+
+    // Return API Gateway compatible response
+    return {
+      statusCode: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*'
+      },
+      body: JSON.stringify(result)
+    };
+  } catch (error) {
+    console.error('Error:', JSON.stringify({
+      error: error.message,
+      stack: error.stack,
+      requestId: context.awsRequestId
+    }));
+
+    return {
+      statusCode: error.statusCode || 500,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        error: error.message || 'Internal server error'
+      })
+    };
+  }
+};
+
+async function processRequest(data) {
+  // Your business logic here
+  const result = await docClient.send(new GetCommand({
+    TableName: process.env.TABLE_NAME,
+    Key: { id: data.id }
+  }));
+  return result.Item;
+}
+```
+
+```python
+# Python Lambda Handler
+# handler.py
+
+import json
+import os
+import logging
+import boto3
+from botocore.exceptions import ClientError
+
+# Initialize outside handler (reused across invocations)
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+dynamodb = boto3.resource('dynamodb')
+table = dynamodb.Table(os.environ['TABLE_NAME'])
+
+def handler(event, context):
+    try:
+        # Parse i
+```
+
+### API Gateway Integration Pattern
+
+REST API and HTTP API integration with Lambda
+
+**When to use**: ['Building REST APIs backed by Lambda', 'Need HTTP endpoints for functions']
+
+```javascript
+```yaml
+# template.yaml (SAM)
+AWSTemplateFormatVersion: '2010-09-09'
+Transform: AWS::Serverless-2016-10-31
+
+Globals:
+  Function:
+    Runtime: nodejs20.x
+    Timeout: 30
+    MemorySize: 256
+    Environment:
+      Variables:
+        TABLE_NAME: !Ref ItemsTable
+
+Resources:
+  # HTTP API (recommended for simple use cases)
+  HttpApi:
+    Type: AWS::Serverless::HttpApi
+    Properties:
+      StageName: prod
+      CorsConfiguration:
+        AllowOrigins:
+          - "*"
+        AllowMethods:
+          - GET
+          - POST
+          - DELETE
+        AllowHeaders:
+          - "*"
+
+  # Lambda Functions
+  GetItemFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: src/handlers/get.handler
+      Events:
+        GetItem:
+          Type: HttpApi
+          Properties:
+            ApiId: !Ref HttpApi
+            Path: /items/{id}
+            Method: GET
+      Policies:
+        - DynamoDBReadPolicy:
+            TableName: !Ref ItemsTable
+
+  CreateItemFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: src/handlers/create.handler
+      Events:
+        CreateItem:
+          Type: HttpApi
+          Properties:
+            ApiId: !Ref HttpApi
+            Path: /items
+            Method: POST
+      Policies:
+        - DynamoDBCrudPolicy:
+            TableName: !Ref ItemsTable
+
+  # DynamoDB Table
+  ItemsTable:
+    Type: AWS::DynamoDB::Table
+    Properties:
+      AttributeDefinitions:
+        - AttributeName: id
+          AttributeType: S
+      KeySchema:
+        - AttributeName: id
+          KeyType: HASH
+      BillingMode: PAY_PER_REQUEST
+
+Outputs:
+  ApiUrl:
+    Value: !Sub "https://${HttpApi}.execute-api.${AWS::Region}.amazonaws.com/prod"
+```
+
+```javascript
+// src/handlers/get.js
+const { getItem } = require('../lib/dynamodb');
+
+exports.handler = async (event) => {
+  const id = event.pathParameters?.id;
+
+  if (!id) {
+    return {
+      statusCode: 400,
+      body: JSON.stringify({ error: 'Missing id parameter' })
+    };
+  }
+
+  const item =
+```
+
+### Event-Driven SQS Pattern
+
+Lambda triggered by SQS for reliable async processing
+
+**When to use**: ['Decoupled, asynchronous processing', 'Need retry logic and DLQ', 'Processing messages in batches']
+
+```python
+```yaml
+# template.yaml
+Resources:
+  ProcessorFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      Handler: src/handlers/processor.handler
+      Events:
+        SQSEvent:
+          Type: SQS
+          Properties:
+            Queue: !GetAtt ProcessingQueue.Arn
+            BatchSize: 10
+            FunctionResponseTypes:
+              - ReportBatchItemFailures  # Partial batch failure handling
+
+  ProcessingQueue:
+    Type: AWS::SQS::Queue
+    Properties:
+      VisibilityTimeout: 180  # 6x Lambda timeout
+      RedrivePolicy:
+        deadLetterTargetArn: !GetAtt DeadLetterQueue.Arn
+        maxReceiveCount: 3
+
+  DeadLetterQueue:
+    Type: AWS::SQS::Queue
+    Properties:
+      MessageRetentionPeriod: 1209600  # 14 days
+```
+
+```javascript
+// src/handlers/processor.js
+exports.handler = async (event) => {
+  const batchItemFailures = [];
+
+  for (const record of event.Records) {
+    try {
+      const body = JSON.parse(record.body);
+      await processMessage(body);
+    } catch (error) {
+      console.error(`Failed to process message ${record.messageId}:`, error);
+      // Report this item as failed (will be retried)
+      batchItemFailures.push({
+        itemIdentifier: record.messageId
+      });
+    }
+  }
+
+  // Return failed items for retry
+  return { batchItemFailures };
+};
+
+async function processMessage(message) {
+  // Your processing logic
+  console.log('Processing:', message);
+
+  // Simulate work
+  await saveToDatabase(message);
+}
+```
+
+```python
+# Python version
+import json
+import logging
+
+logger = logging.getLogger()
+
+def handler(event, context):
+    batch_item_failures = []
+
+    for record in event['Records']:
+        try:
+            body = json.loads(record['body'])
+            process_message(body)
+        except Exception as e:
+            logger.error(f"Failed to process {record['messageId']}: {e}")
+            batch_item_failures.append({
+                'itemIdentifier': record['messageId']
+            })
+
+    return {'batchItemFailures': batch_ite
+```
+
+## Anti-Patterns
+
+### ❌ Monolithic Lambda
+
+**Why bad**: Large deployment packages cause slow cold starts.
+Hard to scale individual operations.
+Updates affect entire system.
+
+### ❌ Large Dependencies
+
+**Why bad**: Increases deployment package size.
+Slows down cold starts significantly.
+Most of SDK/library may be unused.
+
+### ❌ Synchronous Calls in VPC
+
+**Why bad**: VPC-attached Lambdas have ENI setup overhead.
+Blocking DNS lookups or connections worsen cold starts.
+
+## ⚠️ Sharp Edges
+
+| Issue | Severity | Solution |
+|-------|----------|----------|
+| Issue | high | ## Measure your INIT phase |
+| Issue | high | ## Set appropriate timeout |
+| Issue | high | ## Increase memory allocation |
+| Issue | medium | ## Verify VPC configuration |
+| Issue | medium | ## Tell Lambda not to wait for event loop |
+| Issue | medium | ## For large file uploads |
+| Issue | high | ## Use different buckets/prefixes |

package/merged-commands/aws-skills.md

@@ -0,0 +1,22 @@
+---
+name: aws-skills
+description: "AWS development with infrastructure automation and cloud architecture patterns"
+source: "https://github.com/zxkane/aws-skills"
+risk: safe
+---
+
+# Aws Skills
+
+## Overview
+
+AWS development with infrastructure automation and cloud architecture patterns
+
+## When to Use This Skill
+
+Use this skill when you need to work with aws development with infrastructure automation and cloud architecture patterns.
+
+## Instructions
+
+This skill provides guidance and patterns for aws development with infrastructure automation and cloud architecture patterns.
+
+For more information, see the [source repository](https://github.com/zxkane/aws-skills).

package/merged-commands/azd-deployment.md

@@ -0,0 +1,296 @@
+---
+name: azd-deployment
+description: Deploy containerized applications to Azure Container Apps using Azure Developer CLI (azd). Use when setting up azd projects, writing azure.yaml configuration, creating Bicep infrastructure for Container Apps, configuring remote builds with ACR, implementing idempotent deployments, managing environment variables across local/.azure/Bicep, or troubleshooting azd up failures. Triggers on requests for azd configuration, Container Apps deployment, multi-service deployments, and infrastructure-as-code with Bicep.
+---
+
+# Azure Developer CLI (azd) Container Apps Deployment
+
+Deploy containerized frontend + backend applications to Azure Container Apps with remote builds, managed identity, and idempotent infrastructure.
+
+## Quick Start
+
+```bash
+# Initialize and deploy
+azd auth login
+azd init                    # Creates azure.yaml and .azure/ folder
+azd env new <env-name>      # Create environment (dev, staging, prod)
+azd up                      # Provision infra + build + deploy
+```
+
+## Core File Structure
+
+```
+project/
+├── azure.yaml              # azd service definitions + hooks
+├── infra/
+│   ├── main.bicep          # Root infrastructure module
+│   ├── main.parameters.json # Parameter injection from env vars
+│   └── modules/
+│       ├── container-apps-environment.bicep
+│       └── container-app.bicep
+├── .azure/
+│   ├── config.json         # Default environment pointer
+│   └── <env-name>/
+│       ├── .env            # Environment-specific values (azd-managed)
+│       └── config.json     # Environment metadata
+└── src/
+    ├── frontend/Dockerfile
+    └── backend/Dockerfile
+```
+
+## azure.yaml Configuration
+
+### Minimal Configuration
+
+```yaml
+name: my-project
+services:
+  backend:
+    project: ./src/backend
+    language: python
+    host: containerapp
+    docker:
+      path: ./Dockerfile
+      remoteBuild: true
+```
+
+### Full Configuration with Hooks
+
+```yaml
+name: my-project
+metadata:
+  template: my-project@1.0.0
+
+infra:
+  provider: bicep
+  path: ./infra
+
+azure:
+  location: eastus2
+
+services:
+  frontend:
+    project: ./src/frontend
+    language: ts
+    host: containerapp
+    docker:
+      path: ./Dockerfile
+      context: .
+      remoteBuild: true
+
+  backend:
+    project: ./src/backend
+    language: python
+    host: containerapp
+    docker:
+      path: ./Dockerfile
+      context: .
+      remoteBuild: true
+
+hooks:
+  preprovision:
+    shell: sh
+    run: |
+      echo "Before provisioning..."
+      
+  postprovision:
+    shell: sh
+    run: |
+      echo "After provisioning - set up RBAC, etc."
+      
+  postdeploy:
+    shell: sh
+    run: |
+      echo "Frontend: ${SERVICE_FRONTEND_URI}"
+      echo "Backend: ${SERVICE_BACKEND_URI}"
+```
+
+### Key azure.yaml Options
+
+| Option | Description |
+|--------|-------------|
+| `remoteBuild: true` | Build images in Azure Container Registry (recommended) |
+| `context: .` | Docker build context relative to project path |
+| `host: containerapp` | Deploy to Azure Container Apps |
+| `infra.provider: bicep` | Use Bicep for infrastructure |
+
+## Environment Variables Flow
+
+### Three-Level Configuration
+
+1. **Local `.env`** - For local development only
+2. **`.azure/<env>/.env`** - azd-managed, auto-populated from Bicep outputs
+3. **`main.parameters.json`** - Maps env vars to Bicep parameters
+
+### Parameter Injection Pattern
+
+```json
+// infra/main.parameters.json
+{
+  "parameters": {
+    "environmentName": { "value": "${AZURE_ENV_NAME}" },
+    "location": { "value": "${AZURE_LOCATION=eastus2}" },
+    "azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
+  }
+}
+```
+
+Syntax: `${VAR_NAME}` or `${VAR_NAME=default_value}`
+
+### Setting Environment Variables
+
+```bash
+# Set for current environment
+azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
+azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"
+
+# Set during init
+azd env new prod
+azd env set AZURE_OPENAI_ENDPOINT "..." 
+```
+
+### Bicep Output → Environment Variable
+
+```bicep
+// In main.bicep - outputs auto-populate .azure/<env>/.env
+output SERVICE_FRONTEND_URI string = frontend.outputs.uri
+output SERVICE_BACKEND_URI string = backend.outputs.uri
+output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId
+```
+
+## Idempotent Deployments
+
+### Why azd up is Idempotent
+
+1. **Bicep is declarative** - Resources reconcile to desired state
+2. **Remote builds tag uniquely** - Image tags include deployment timestamp
+3. **ACR reuses layers** - Only changed layers upload
+
+### Preserving Manual Changes
+
+Custom domains added via Portal can be lost on redeploy. Preserve with hooks:
+
+```yaml
+hooks:
+  preprovision:
+    shell: sh
+    run: |
+      # Save custom domains before provision
+      if az containerapp show --name "$FRONTEND_NAME" -g "$RG" &>/dev/null; then
+        az containerapp show --name "$FRONTEND_NAME" -g "$RG" \
+          --query "properties.configuration.ingress.customDomains" \
+          -o json > /tmp/domains.json
+      fi
+
+  postprovision:
+    shell: sh
+    run: |
+      # Verify/restore custom domains
+      if [ -f /tmp/domains.json ]; then
+        echo "Saved domains: $(cat /tmp/domains.json)"
+      fi
+```
+
+### Handling Existing Resources
+
+```bicep
+// Reference existing ACR (don't recreate)
+resource containerRegistry 'Microsoft.ContainerRegistry/registries@2023-07-01' existing = {
+  name: containerRegistryName
+}
+
+// Set customDomains to null to preserve Portal-added domains
+customDomains: empty(customDomainsParam) ? null : customDomainsParam
+```
+
+## Container App Service Discovery
+
+Internal HTTP routing between Container Apps in same environment:
+
+```bicep
+// Backend reference in frontend env vars
+env: [
+  {
+    name: 'BACKEND_URL'
+    value: 'http://ca-backend-${resourceToken}'  // Internal DNS
+  }
+]
+```
+
+Frontend nginx proxies to internal URL:
+```nginx
+location /api {
+    proxy_pass $BACKEND_URL;
+}
+```
+
+## Managed Identity & RBAC
+
+### Enable System-Assigned Identity
+
+```bicep
+resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
+  identity: {
+    type: 'SystemAssigned'
+  }
+}
+
+output principalId string = containerApp.identity.principalId
+```
+
+### Post-Provision RBAC Assignment
+
+```yaml
+hooks:
+  postprovision:
+    shell: sh
+    run: |
+      PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
+      
+      # Azure OpenAI access
+      az role assignment create \
+        --assignee-object-id "$PRINCIPAL_ID" \
+        --assignee-principal-type ServicePrincipal \
+        --role "Cognitive Services OpenAI User" \
+        --scope "$OPENAI_RESOURCE_ID" 2>/dev/null || true
+      
+      # Azure AI Search access
+      az role assignment create \
+        --assignee-object-id "$PRINCIPAL_ID" \
+        --role "Search Index Data Reader" \
+        --scope "$SEARCH_RESOURCE_ID" 2>/dev/null || true
+```
+
+## Common Commands
+
+```bash
+# Environment management
+azd env list                        # List environments
+azd env select <name>               # Switch environment
+azd env get-values                  # Show all env vars
+azd env set KEY value               # Set variable
+
+# Deployment
+azd up                              # Full provision + deploy
+azd provision                       # Infrastructure only
+azd deploy                          # Code deployment only
+azd deploy --service backend        # Deploy single service
+
+# Debugging
+azd show                            # Show project status
+az containerapp logs show -n <app> -g <rg> --follow  # Stream logs
+```
+
+## Reference Files
+
+- **Bicep patterns**: See [references/bicep-patterns.md](references/bicep-patterns.md) for Container Apps modules
+- **Troubleshooting**: See [references/troubleshooting.md](references/troubleshooting.md) for common issues
+- **azure.yaml schema**: See [references/azure-yaml-schema.md](references/azure-yaml-schema.md) for full options
+
+## Critical Reminders
+
+1. **Always use `remoteBuild: true`** - Local builds fail on M1/ARM Macs deploying to AMD64
+2. **Bicep outputs auto-populate .azure/<env>/.env** - Don't manually edit
+3. **Use `azd env set` for secrets** - Not main.parameters.json defaults
+4. **Service tags (`azd-service-name`)** - Required for azd to find Container Apps
+5. **`|| true` in hooks** - Prevent RBAC "already exists" errors from failing deploy