moai-adk 0.8.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-neon/modules/auto-scaling.md

@@ -0,0 +1,349 @@
+# Auto-Scaling and Compute Management
+
+## Overview
+
+Neon auto-scaling automatically adjusts compute resources based on workload demand, with scale-to-zero capability for cost optimization during idle periods.
+
+---
+
+## Compute Unit Specifications
+
+### Available Compute Sizes
+
+0.25 CU Specifications:
+- vCPU: 0.25
+- RAM: 1 GB
+- Use Case: Development, testing, low-traffic applications
+
+0.5 CU Specifications:
+- vCPU: 0.5
+- RAM: 2 GB
+- Use Case: Light production workloads, staging environments
+
+1 CU Specifications:
+- vCPU: 1
+- RAM: 4 GB
+- Use Case: Standard production applications
+
+2 CU Specifications:
+- vCPU: 2
+- RAM: 8 GB
+- Use Case: Medium workloads, moderate traffic
+
+4 CU Specifications:
+- vCPU: 4
+- RAM: 16 GB
+- Use Case: Heavy workloads, high traffic applications
+
+8 CU Specifications:
+- vCPU: 8
+- RAM: 32 GB
+- Use Case: High-performance requirements, data processing
+
+---
+
+## Auto-Scaling Configuration
+
+### Configuration via API
+
+```typescript
+interface AutoScalingConfig {
+  minCu: number      // Minimum compute units (0.25 for scale-to-zero)
+  maxCu: number      // Maximum compute units
+  suspendTimeout: number  // Seconds before suspension (0 to disable)
+}
+
+async function configureAutoScaling(endpointId: string, config: AutoScalingConfig) {
+  const response = await fetch(
+    `https://console.neon.tech/api/v2/projects/${process.env.NEON_PROJECT_ID}/endpoints/${endpointId}`,
+    {
+      method: 'PATCH',
+      headers: {
+        'Authorization': `Bearer ${process.env.NEON_API_KEY}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        endpoint: {
+          autoscaling_limit_min_cu: config.minCu,
+          autoscaling_limit_max_cu: config.maxCu,
+          suspend_timeout_seconds: config.suspendTimeout
+        }
+      })
+    }
+  )
+
+  if (!response.ok) {
+    throw new Error(`Failed to configure auto-scaling: ${response.statusText}`)
+  }
+
+  return response.json()
+}
+```
+
+### Environment-Specific Configurations
+
+Development Configuration:
+```typescript
+const devConfig: AutoScalingConfig = {
+  minCu: 0.25,        // Scale to zero when idle
+  maxCu: 0.5,         // Limited compute for development
+  suspendTimeout: 300  // Suspend after 5 minutes idle
+}
+```
+
+Staging Configuration:
+```typescript
+const stagingConfig: AutoScalingConfig = {
+  minCu: 0.25,        // Scale to zero during off-hours
+  maxCu: 1,           // Moderate compute for testing
+  suspendTimeout: 600  // Suspend after 10 minutes idle
+}
+```
+
+Production Configuration:
+```typescript
+const productionConfig: AutoScalingConfig = {
+  minCu: 0.5,         // Always-on minimum for faster response
+  maxCu: 4,           // Scale up for peak traffic
+  suspendTimeout: 3600 // Suspend after 1 hour idle (or 0 to disable)
+}
+```
+
+High-Traffic Production Configuration:
+```typescript
+const highTrafficConfig: AutoScalingConfig = {
+  minCu: 1,           // Higher baseline for consistent performance
+  maxCu: 8,           // Maximum scale for peak loads
+  suspendTimeout: 0   // Never suspend (always-on)
+}
+```
+
+---
+
+## Scale-to-Zero Behavior
+
+### How Scale-to-Zero Works
+
+Idle Detection: Neon monitors connection activity and query execution
+Suspension: After suspend_timeout seconds of inactivity, compute suspends
+Wake-Up: First connection request triggers automatic wake-up
+Cold Start: Typical wake-up time is 500ms to 2 seconds
+
+### Cold Start Optimization
+
+Connection Pooling Impact:
+- Use pooled connections to reduce cold start frequency
+- Pooler maintains connection state during suspension
+- First query after wake-up experiences latency
+
+Warming Strategies:
+```typescript
+// Health check endpoint to keep database warm
+async function warmDatabase() {
+  const sql = neon(process.env.DATABASE_URL_POOLED!)
+
+  // Simple query to prevent suspension
+  await sql`SELECT 1`
+}
+
+// Schedule periodic warming (every 4 minutes for 5-minute timeout)
+setInterval(warmDatabase, 4 * 60 * 1000)
+```
+
+### Cost Implications
+
+Scale-to-Zero Benefits:
+- Zero compute charges during idle periods
+- Ideal for development and low-traffic applications
+- Automatic cost optimization without manual intervention
+
+Trade-offs:
+- Cold start latency on first request after suspension
+- Not suitable for latency-sensitive applications
+- Consider always-on minimum for production workloads
+
+---
+
+## Endpoint Management
+
+### Get Current Endpoint Configuration
+
+```typescript
+async function getEndpointConfig(endpointId: string) {
+  const response = await fetch(
+    `https://console.neon.tech/api/v2/projects/${process.env.NEON_PROJECT_ID}/endpoints/${endpointId}`,
+    {
+      headers: {
+        'Authorization': `Bearer ${process.env.NEON_API_KEY}`
+      }
+    }
+  )
+
+  return response.json()
+}
+```
+
+### List All Endpoints
+
+```typescript
+async function listEndpoints() {
+  const response = await fetch(
+    `https://console.neon.tech/api/v2/projects/${process.env.NEON_PROJECT_ID}/endpoints`,
+    {
+      headers: {
+        'Authorization': `Bearer ${process.env.NEON_API_KEY}`
+      }
+    }
+  )
+
+  return response.json()
+}
+```
+
+### Monitor Endpoint Status
+
+```typescript
+interface EndpointStatus {
+  id: string
+  state: 'active' | 'idle' | 'suspended'
+  currentCu: number
+  lastActiveAt: string
+}
+
+async function getEndpointStatus(endpointId: string): Promise<EndpointStatus> {
+  const { endpoint } = await getEndpointConfig(endpointId)
+
+  return {
+    id: endpoint.id,
+    state: endpoint.current_state,
+    currentCu: endpoint.autoscaling_limit_min_cu,
+    lastActiveAt: endpoint.last_active
+  }
+}
+```
+
+---
+
+## Cost Optimization Strategies
+
+### Development Environments
+
+Strategy: Aggressive scale-to-zero with low maximum compute
+
+```typescript
+// Minimize costs for development databases
+await configureAutoScaling(devEndpointId, {
+  minCu: 0.25,
+  maxCu: 0.5,
+  suspendTimeout: 180  // 3 minutes - quick suspension
+})
+```
+
+### Staging Environments
+
+Strategy: Balance between cost and performance for testing
+
+```typescript
+// Cost-effective staging with reasonable performance
+await configureAutoScaling(stagingEndpointId, {
+  minCu: 0.25,
+  maxCu: 2,
+  suspendTimeout: 600  // 10 minutes
+})
+```
+
+### Production Environments
+
+Strategy: Prioritize performance with cost awareness
+
+```typescript
+// Production with always-on minimum
+await configureAutoScaling(prodEndpointId, {
+  minCu: 0.5,         // Avoid cold starts
+  maxCu: 4,           // Handle traffic spikes
+  suspendTimeout: 0   // Never suspend
+})
+```
+
+### Off-Hours Optimization
+
+```typescript
+// Reduce compute during off-peak hours
+async function adjustForOffHours(endpointId: string, isOffHours: boolean) {
+  const config = isOffHours
+    ? { minCu: 0.25, maxCu: 1, suspendTimeout: 300 }
+    : { minCu: 0.5, maxCu: 4, suspendTimeout: 0 }
+
+  await configureAutoScaling(endpointId, config)
+}
+
+// Schedule-based adjustment
+const hour = new Date().getUTCHours()
+const isOffHours = hour >= 2 && hour < 8  // 2 AM - 8 AM UTC
+await adjustForOffHours(productionEndpointId, isOffHours)
+```
+
+---
+
+## Monitoring and Alerts
+
+### Compute Usage Tracking
+
+```typescript
+interface ComputeMetrics {
+  currentCu: number
+  avgCu: number
+  peakCu: number
+  suspendedMinutes: number
+  activeMinutes: number
+}
+
+async function getComputeMetrics(endpointId: string): Promise<ComputeMetrics> {
+  // Fetch from Neon console API or monitoring integration
+  const { endpoint } = await getEndpointConfig(endpointId)
+
+  return {
+    currentCu: endpoint.current_state === 'active' ? endpoint.autoscaling_limit_min_cu : 0,
+    avgCu: 0,  // Calculate from historical data
+    peakCu: endpoint.autoscaling_limit_max_cu,
+    suspendedMinutes: 0,  // Calculate from suspension logs
+    activeMinutes: 0  // Calculate from activity logs
+  }
+}
+```
+
+### Alert Thresholds
+
+High Compute Alert: Notify when consistently at max CU
+Frequent Suspensions: Alert if cold starts affecting performance
+Cost Threshold: Alert when monthly compute exceeds budget
+
+---
+
+## Best Practices
+
+### Configuration Guidelines
+
+Development: Use 0.25-0.5 CU range with short suspension timeout
+Staging: Use 0.25-2 CU range with moderate suspension timeout
+Production: Use 0.5-4 CU range, consider disabling suspension for critical apps
+High-Traffic: Use 1-8 CU range with suspension disabled
+
+### Performance Considerations
+
+Connection Pooling: Always use pooled connections with auto-scaling
+Query Optimization: Optimize queries to reduce compute time
+Indexing: Proper indexes reduce CPU usage and allow smaller compute
+Caching: Implement application-level caching to reduce database load
+
+### Cost Management
+
+Monitor Usage: Track compute hours and identify optimization opportunities
+Right-Size: Adjust max CU based on actual peak usage
+Schedule Scaling: Reduce compute during known low-traffic periods
+Branch Cleanup: Delete unused branches to avoid dormant compute costs
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06

moai_adk/templates/.claude/skills/moai-platform-neon/modules/branching-workflows.md

@@ -0,0 +1,354 @@
+# Database Branching Workflows
+
+## Overview
+
+Neon database branching creates instant copy-on-write clones of your database, enabling isolated development environments, preview deployments, and safe testing with production data.
+
+---
+
+## Core Concepts
+
+### Copy-on-Write Architecture
+
+Branch Creation: Instant creation with no data copying
+Storage Efficiency: Branches share unchanged data with parent
+Write Isolation: Changes in branch do not affect parent
+Inheritance: New data in parent does not propagate to existing branches
+
+### Branch Types
+
+Main Branch: Primary production database
+Development Branch: Long-lived branch for development work
+Feature Branch: Short-lived branch for specific features
+Preview Branch: Ephemeral branch for PR preview environments
+Restore Branch: Branch created for point-in-time recovery
+
+---
+
+## Branch Management API
+
+### NeonBranchManager Implementation
+
+```typescript
+class NeonBranchManager {
+  private apiKey: string
+  private projectId: string
+  private baseUrl = 'https://console.neon.tech/api/v2'
+
+  constructor(apiKey: string, projectId: string) {
+    this.apiKey = apiKey
+    this.projectId = projectId
+  }
+
+  private async request(path: string, options: RequestInit = {}) {
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        ...options.headers
+      }
+    })
+    if (!response.ok) throw new Error(`Neon API error: ${response.statusText}`)
+    return response.json()
+  }
+
+  async createBranch(name: string, parentId: string = 'main') {
+    return this.request(`/projects/${this.projectId}/branches`, {
+      method: 'POST',
+      body: JSON.stringify({
+        branch: { name, parent_id: parentId }
+      })
+    })
+  }
+
+  async deleteBranch(branchId: string) {
+    return this.request(`/projects/${this.projectId}/branches/${branchId}`, {
+      method: 'DELETE'
+    })
+  }
+
+  async listBranches() {
+    return this.request(`/projects/${this.projectId}/branches`)
+  }
+
+  async getBranchConnectionString(branchId: string) {
+    const endpoints = await this.request(
+      `/projects/${this.projectId}/branches/${branchId}/endpoints`
+    )
+    return endpoints.endpoints[0]?.connection_uri
+  }
+}
+```
+
+---
+
+## Preview Environment Pattern
+
+### Per-PR Database Branches
+
+```typescript
+async function createPreviewEnvironment(prNumber: number) {
+  const branchManager = new NeonBranchManager(
+    process.env.NEON_API_KEY!,
+    process.env.NEON_PROJECT_ID!
+  )
+
+  // Create branch from main with PR identifier
+  const branch = await branchManager.createBranch(`pr-${prNumber}`, 'main')
+
+  // Get connection string for the new branch
+  const connectionString = await branchManager.getBranchConnectionString(branch.branch.id)
+
+  return {
+    branchId: branch.branch.id,
+    branchName: branch.branch.name,
+    connectionString,
+    createdAt: new Date().toISOString()
+  }
+}
+
+async function cleanupPreviewEnvironment(prNumber: number) {
+  const branchManager = new NeonBranchManager(
+    process.env.NEON_API_KEY!,
+    process.env.NEON_PROJECT_ID!
+  )
+
+  // Find and delete the PR branch
+  const { branches } = await branchManager.listBranches()
+  const prBranch = branches.find(b => b.name === `pr-${prNumber}`)
+
+  if (prBranch) {
+    await branchManager.deleteBranch(prBranch.id)
+  }
+}
+```
+
+---
+
+## GitHub Actions Integration
+
+### Preview Environment Workflow
+
+```yaml
+name: Preview Environment
+
+on:
+  pull_request:
+    types: [opened, synchronize, closed]
+
+env:
+  NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+  NEON_PROJECT_ID: ${{ secrets.NEON_PROJECT_ID }}
+
+jobs:
+  create-preview:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    outputs:
+      branch_id: ${{ steps.create-branch.outputs.branch_id }}
+      database_url: ${{ steps.create-branch.outputs.database_url }}
+    steps:
+      - name: Create Neon Branch
+        id: create-branch
+        run: |
+          RESPONSE=$(curl -s -X POST \
+            -H "Authorization: Bearer $NEON_API_KEY" \
+            -H "Content-Type: application/json" \
+            -d '{"branch":{"name":"pr-${{ github.event.number }}"}}' \
+            "https://console.neon.tech/api/v2/projects/$NEON_PROJECT_ID/branches")
+
+          BRANCH_ID=$(echo $RESPONSE | jq -r '.branch.id')
+          echo "branch_id=$BRANCH_ID" >> $GITHUB_OUTPUT
+
+          # Get connection string
+          ENDPOINTS=$(curl -s \
+            -H "Authorization: Bearer $NEON_API_KEY" \
+            "https://console.neon.tech/api/v2/projects/$NEON_PROJECT_ID/branches/$BRANCH_ID/endpoints")
+
+          DATABASE_URL=$(echo $ENDPOINTS | jq -r '.endpoints[0].connection_uri')
+          echo "database_url=$DATABASE_URL" >> $GITHUB_OUTPUT
+
+      - name: Comment PR with Database URL
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `Preview database created: \`pr-${{ github.event.number }}\`\n\nBranch ID: \`${{ steps.create-branch.outputs.branch_id }}\``
+            })
+
+  deploy-preview:
+    needs: create-preview
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Migrations
+        env:
+          DATABASE_URL: ${{ needs.create-preview.outputs.database_url }}
+        run: |
+          npm ci
+          npm run db:migrate
+
+      - name: Deploy Preview
+        env:
+          DATABASE_URL: ${{ needs.create-preview.outputs.database_url }}
+        run: |
+          # Deploy to preview environment (Vercel, Netlify, etc.)
+          echo "Deploying with preview database..."
+
+  cleanup-preview:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Find Branch ID
+        id: find-branch
+        run: |
+          BRANCHES=$(curl -s \
+            -H "Authorization: Bearer $NEON_API_KEY" \
+            "https://console.neon.tech/api/v2/projects/$NEON_PROJECT_ID/branches")
+
+          BRANCH_ID=$(echo $BRANCHES | jq -r '.branches[] | select(.name == "pr-${{ github.event.number }}") | .id')
+          echo "branch_id=$BRANCH_ID" >> $GITHUB_OUTPUT
+
+      - name: Delete Neon Branch
+        if: steps.find-branch.outputs.branch_id != ''
+        run: |
+          curl -X DELETE \
+            -H "Authorization: Bearer $NEON_API_KEY" \
+            "https://console.neon.tech/api/v2/projects/$NEON_PROJECT_ID/branches/${{ steps.find-branch.outputs.branch_id }}"
+```
+
+---
+
+## Development Workflow Pattern
+
+### Feature Branch Database
+
+```typescript
+interface FeatureBranchConfig {
+  featureName: string
+  baseBranch?: string
+  autoCleanupDays?: number
+}
+
+async function createFeatureBranch(config: FeatureBranchConfig) {
+  const { featureName, baseBranch = 'main', autoCleanupDays = 7 } = config
+
+  const branchManager = new NeonBranchManager(
+    process.env.NEON_API_KEY!,
+    process.env.NEON_PROJECT_ID!
+  )
+
+  // Create branch with feature prefix
+  const branchName = `feature-${featureName}-${Date.now()}`
+  const branch = await branchManager.createBranch(branchName, baseBranch)
+
+  // Store cleanup metadata
+  const metadata = {
+    branchId: branch.branch.id,
+    branchName,
+    featureName,
+    createdAt: new Date().toISOString(),
+    expiresAt: new Date(Date.now() + autoCleanupDays * 24 * 60 * 60 * 1000).toISOString()
+  }
+
+  return {
+    ...metadata,
+    connectionString: await branchManager.getBranchConnectionString(branch.branch.id)
+  }
+}
+
+async function cleanupExpiredBranches() {
+  const branchManager = new NeonBranchManager(
+    process.env.NEON_API_KEY!,
+    process.env.NEON_PROJECT_ID!
+  )
+
+  const { branches } = await branchManager.listBranches()
+  const now = new Date()
+
+  for (const branch of branches) {
+    // Check if branch is a feature branch and expired
+    if (branch.name.startsWith('feature-')) {
+      const createdAt = new Date(branch.created_at)
+      const ageInDays = (now.getTime() - createdAt.getTime()) / (24 * 60 * 60 * 1000)
+
+      if (ageInDays > 7) {
+        console.log(`Cleaning up expired branch: ${branch.name}`)
+        await branchManager.deleteBranch(branch.id)
+      }
+    }
+  }
+}
+```
+
+---
+
+## Branch Reset Pattern
+
+### Reset Branch to Parent State
+
+```typescript
+async function resetBranchToParent(branchName: string) {
+  const branchManager = new NeonBranchManager(
+    process.env.NEON_API_KEY!,
+    process.env.NEON_PROJECT_ID!
+  )
+
+  // Find the current branch
+  const { branches } = await branchManager.listBranches()
+  const currentBranch = branches.find(b => b.name === branchName)
+
+  if (!currentBranch) {
+    throw new Error(`Branch ${branchName} not found`)
+  }
+
+  const parentId = currentBranch.parent_id
+
+  // Delete current branch
+  await branchManager.deleteBranch(currentBranch.id)
+
+  // Recreate with same name from parent
+  const newBranch = await branchManager.createBranch(branchName, parentId)
+
+  return {
+    branchId: newBranch.branch.id,
+    connectionString: await branchManager.getBranchConnectionString(newBranch.branch.id),
+    resetAt: new Date().toISOString()
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### Branch Naming Conventions
+
+Preview Branches: pr-{number} for pull request previews
+Feature Branches: feature-{name}-{timestamp} for development
+Staging Branches: staging or staging-{version} for staging environments
+Restore Branches: restore-{timestamp} for point-in-time recovery
+
+### Lifecycle Management
+
+Automatic Cleanup: Configure scheduled cleanup for expired branches
+Branch Limits: Monitor branch count against project limits
+Connection Management: Use pooled connections for branch databases
+Cost Awareness: Branches consume compute when active
+
+### Security Considerations
+
+Sensitive Data: Consider data masking for non-production branches
+Access Control: Limit API key permissions for branch operations
+Audit Trail: Log branch creation and deletion operations
+Credential Rotation: Rotate branch credentials on schedule
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06