moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-platform-railway/reference.md

@@ -0,0 +1,374 @@
+# Railway Platform Reference
+
+Extended documentation for Railway container deployment configurations and advanced patterns.
+
+---
+
+## Railway Environment Variables
+
+### System-Provided Variables
+
+Railway automatically injects these environment variables into every deployment:
+
+Service Information:
+- RAILWAY_SERVICE_NAME: Name of the current service
+- RAILWAY_REPLICA_ID: Unique identifier for this replica
+- RAILWAY_ENVIRONMENT: Environment name (production, staging)
+- RAILWAY_PROJECT_ID: Project identifier
+- RAILWAY_DEPLOYMENT_ID: Current deployment identifier
+
+Git Information:
+- RAILWAY_GIT_COMMIT_SHA: Full commit SHA
+- RAILWAY_GIT_AUTHOR: Commit author
+- RAILWAY_GIT_BRANCH: Branch name
+- RAILWAY_GIT_REPO_OWNER: Repository owner
+- RAILWAY_GIT_REPO_NAME: Repository name
+
+Networking:
+- RAILWAY_PRIVATE_DOMAIN: Internal hostname for private networking
+- RAILWAY_PUBLIC_DOMAIN: Public hostname (if configured)
+- PORT: Port to bind to (Railway expects this)
+
+Volume:
+- RAILWAY_VOLUME_NAME: Name of attached volume
+- RAILWAY_VOLUME_MOUNT_PATH: Mount path for volume
+
+### Variable Best Practices
+
+Environment-Specific Configuration:
+- Use Railway environments (production, staging, development)
+- Override variables per environment in dashboard
+- Never commit secrets to repository
+
+Secret Management:
+- Store secrets in Railway dashboard only
+- Use variable references for shared secrets between services
+- Rotate secrets through environment variable updates
+
+---
+
+## railway.toml Configuration Reference
+
+### Build Section
+
+```toml
+[build]
+# Builder selection: DOCKERFILE, RAILPACK, or NIXPACKS (deprecated)
+builder = "DOCKERFILE"
+
+# Dockerfile path (relative to railway.toml)
+dockerfilePath = "./Dockerfile"
+
+# Build command (for non-Docker builds)
+buildCommand = "npm run build"
+
+# Files that trigger rebuild
+watchPatterns = ["src/**", "package.json", "Dockerfile"]
+
+# Build arguments
+[build.args]
+NODE_ENV = "production"
+```
+
+### Deploy Section
+
+```toml
+[deploy]
+# Start command (overrides Dockerfile CMD)
+startCommand = "node dist/main.js"
+
+# Health check configuration
+healthcheckPath = "/health"
+healthcheckTimeout = 60
+
+# Restart policy: ON_FAILURE, ALWAYS, NEVER
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 5
+
+# Number of replicas (1 if using volumes)
+numReplicas = 2
+
+# Cron schedule for scheduled services
+cronSchedule = "0 * * * *"
+```
+
+### Resources Section
+
+```toml
+[deploy.resources]
+# Memory limit (Mi or Gi)
+memory = "512Mi"
+
+# CPU allocation (cores)
+cpu = "0.5"
+```
+
+### Scaling Section
+
+```toml
+[deploy.scaling]
+# Replica range
+minReplicas = 2
+maxReplicas = 10
+
+# Resource-based triggers
+targetCPUUtilization = 70
+targetMemoryUtilization = 80
+
+# Request-based triggers
+targetRequestsPerSecond = 100
+
+# Cooldown settings
+scaleDownDelaySeconds = 300
+```
+
+### Volume Section
+
+```toml
+[[volumes]]
+mountPath = "/app/data"
+name = "app-data"
+size = "10Gi"
+```
+
+### Region Section
+
+```toml
+[[deploy.regions]]
+name = "us-west1"
+replicas = 3
+
+[[deploy.regions]]
+name = "europe-west4"
+replicas = 2
+```
+
+---
+
+## Railway CLI Reference
+
+### Authentication
+
+```bash
+railway login              # Interactive login
+railway login --browserless  # Token-based login
+railway logout             # Logout
+railway whoami             # Show current user
+```
+
+### Project Management
+
+```bash
+railway init               # Initialize new project
+railway link               # Link to existing project
+railway unlink             # Unlink from project
+railway status             # Show project status
+```
+
+### Deployment
+
+```bash
+railway up                 # Deploy current directory
+railway up --detach        # Deploy without waiting for logs
+railway up --service NAME  # Deploy specific service
+railway up --environment ENV  # Deploy to specific environment
+```
+
+### Environment Variables
+
+```bash
+railway variables          # List all variables
+railway variables --set KEY=value  # Set variable
+railway variables --unset KEY      # Remove variable
+railway variables --json   # Output as JSON
+```
+
+### Logs and Monitoring
+
+```bash
+railway logs               # Stream logs
+railway logs --service NAME  # Logs for specific service
+railway logs --filter error  # Filter logs
+railway logs --lines 100   # Limit lines
+```
+
+### Deployment Management
+
+```bash
+railway deployments        # List deployments
+railway deployments list   # Same as above
+railway rollback DEPLOY_ID # Rollback to specific deployment
+railway rollback --previous  # Rollback to previous deployment
+```
+
+### Database Operations
+
+```bash
+railway connect            # Connect to database
+railway run COMMAND        # Run command with Railway env
+```
+
+---
+
+## Managed Services
+
+### PostgreSQL
+
+Configuration:
+- Automatic connection pooling via PgBouncer
+- Point-in-time recovery
+- Automatic backups
+
+Connection URL Format:
+```
+postgresql://user:password@host:port/database?sslmode=require
+```
+
+### Redis
+
+Configuration:
+- Persistence enabled by default
+- Memory limits based on plan
+- Cluster mode available on higher plans
+
+Connection URL Format:
+```
+redis://default:password@host:port
+```
+
+### MySQL
+
+Configuration:
+- InnoDB storage engine
+- Automatic backups
+- Binary logging enabled
+
+Connection URL Format:
+```
+mysql://user:password@host:port/database
+```
+
+---
+
+## Networking Details
+
+### Port Binding
+
+Railway expects applications to bind to the PORT environment variable:
+
+```typescript
+const port = process.env.PORT || 3000
+app.listen(port, '0.0.0.0', () => {
+  console.log(`Server running on port ${port}`)
+})
+```
+
+Common Pitfall: Binding to localhost (127.0.0.1) instead of 0.0.0.0 will prevent Railway from routing traffic.
+
+### Private Networking Internals
+
+Private domains use Railway's internal DNS:
+- Format: {service-name}.railway.internal
+- Resolution only works within Railway network
+- No additional configuration needed
+
+Service-to-Service Latency:
+- Same region: < 1ms
+- Cross-region: 50-150ms depending on distance
+
+### SSL/TLS
+
+Public Domains:
+- Automatic Let's Encrypt certificates
+- Wildcard certificates for custom domains
+- HTTP to HTTPS redirect automatic
+
+Private Networking:
+- No TLS by default (internal network is encrypted)
+- Can add TLS if compliance requires end-to-end encryption
+
+---
+
+## Limits and Quotas
+
+### Free Tier
+
+- $5/month credit
+- 512 MB RAM per service
+- 1 vCPU per service
+- Limited to 2 services per project
+
+### Pro Tier
+
+- Usage-based pricing
+- Up to 32 GB RAM per service
+- Up to 8 vCPU per service
+- Unlimited services
+- Priority support
+
+### Resource Limits
+
+Maximum Values:
+- Memory: 32 Gi
+- CPU: 8 cores
+- Volume size: 100 Gi
+- Replicas: 20 per service
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+Build Failures:
+- Check Dockerfile syntax
+- Verify base image availability
+- Review build logs for errors
+
+Deployment Crashes:
+- Check health check path returns 200
+- Verify PORT binding
+- Review application logs
+
+Networking Issues:
+- Confirm private domain format
+- Check service is running
+- Verify variable references
+
+Volume Issues:
+- Volumes require numReplicas = 1
+- Check mount path permissions
+- Verify volume size sufficient
+
+### Debug Commands
+
+```bash
+railway logs --service NAME  # Application logs
+railway status              # Service status
+railway variables           # Environment check
+railway run sh              # Shell access (if available)
+```
+
+---
+
+## Version History
+
+Version 2.0.0 (2025-12-30):
+- Modular documentation structure
+- Context7 MCP integration
+- Railpack migration guidance
+- Enhanced auto-scaling patterns
+
+Version 1.1.0 (2025-11-15):
+- Multi-region deployment
+- Volume configuration
+- CI/CD integration
+
+Version 1.0.0 (2025-10-01):
+- Initial release
+- Docker deployment patterns
+- Multi-service architecture
+
+---
+
+Status: Production Ready | Updated: 2025-12-30

moai_adk/templates/.claude/skills/moai-platform-supabase/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: "moai-platform-supabase"
+description: "Supabase specialist covering PostgreSQL 16, pgvector, RLS, real-time subscriptions, and Edge Functions. Use when building full-stack apps with Supabase backend."
+version: 2.0.0
+category: "platform"
+modularized: true
+tags: ['supabase', 'postgresql', 'pgvector', 'realtime', 'rls', 'edge-functions']
+context7-libraries: ['/supabase/supabase']
+related-skills: ['moai-platform-neon', 'moai-lang-typescript']
+updated: 2026-01-08
+status: "active"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# moai-platform-supabase: Supabase Platform Specialist
+
+## Quick Reference (30 seconds)
+
+Supabase Full-Stack Platform: PostgreSQL 16 with pgvector for AI/vector search, Row-Level Security for multi-tenant apps, real-time subscriptions, Edge Functions with Deno runtime, and integrated Storage with transformations.
+
+### Core Capabilities
+
+PostgreSQL 16: Latest PostgreSQL with full SQL support, JSONB, and advanced features
+pgvector Extension: AI embeddings storage with HNSW/IVFFlat indexes for similarity search
+Row-Level Security: Automatic multi-tenant data isolation at database level
+Real-time Subscriptions: Live data sync via Postgres Changes and Presence
+Edge Functions: Serverless Deno functions at the edge
+Storage: File storage with automatic image transformations
+Auth: Built-in authentication with JWT integration
+
+### When to Use Supabase
+
+- Multi-tenant SaaS applications requiring data isolation
+- AI/ML applications needing vector embeddings and similarity search
+- Real-time collaborative features (presence, live updates)
+- Full-stack applications needing auth, database, and storage
+- Projects requiring PostgreSQL-specific features
+
+### Context7 Documentation Access
+
+For latest Supabase API documentation, use the Context7 MCP tools:
+
+Step 1 - Resolve library ID:
+Use mcp__context7__resolve-library-id with query "supabase" to get the Context7-compatible library ID
+
+Step 2 - Fetch documentation:
+Use mcp__context7__get-library-docs with the resolved library ID, specifying topic and token allocation
+
+Example topics: "postgresql pgvector", "row-level-security policies", "realtime subscriptions presence", "edge-functions deno", "storage transformations", "auth jwt"
+
+---
+
+## Module Index
+
+This skill uses progressive disclosure with specialized modules for detailed implementation patterns.
+
+### Core Modules
+
+**postgresql-pgvector** - PostgreSQL 16 with pgvector extension for AI embeddings and semantic search
+- Vector storage with 1536-dimension OpenAI embeddings
+- HNSW and IVFFlat index strategies
+- Semantic search functions
+- Hybrid search combining vector and full-text
+
+**row-level-security** - RLS policies for multi-tenant data isolation
+- Basic tenant isolation patterns
+- Hierarchical organization access
+- Role-based modification policies
+- Service role bypass for server operations
+
+**realtime-presence** - Real-time subscriptions and presence tracking
+- Postgres Changes subscription patterns
+- Filtered change listeners
+- Presence state management
+- Collaborative cursor and typing indicators
+
+**edge-functions** - Serverless Deno functions at the edge
+- Basic Edge Function with authentication
+- CORS header configuration
+- JWT token verification
+- Rate limiting implementation
+
+**storage-cdn** - File storage with image transformations
+- File upload patterns
+- Image transformation URLs
+- Thumbnail generation
+- Cache control configuration
+
+**auth-integration** - Authentication patterns and JWT handling
+- Server-side client creation
+- Cookie-based session management
+- Auth state synchronization
+- Protected route patterns
+
+**typescript-patterns** - TypeScript client patterns and service layers
+- Server-side client for Next.js App Router
+- Service layer abstraction pattern
+- Subscription management
+- Type-safe database operations
+
+---
+
+## Quick Start Patterns
+
+### Database Setup
+
+Enable pgvector extension and create embeddings table:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE documents (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  content TEXT NOT NULL,
+  embedding vector(1536),
+  metadata JSONB DEFAULT '{}',
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+CREATE INDEX idx_documents_embedding ON documents
+USING hnsw (embedding vector_cosine_ops);
+```
+
+### Basic RLS Policy
+
+```sql
+ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "tenant_isolation" ON projects FOR ALL
+  USING (tenant_id = (auth.jwt() ->> 'tenant_id')::UUID);
+```
+
+### Real-time Subscription
+
+```typescript
+const channel = supabase.channel('db-changes')
+  .on('postgres_changes',
+    { event: '*', schema: 'public', table: 'messages' },
+    (payload) => console.log('Change:', payload)
+  )
+  .subscribe()
+```
+
+### Edge Function Template
+
+```typescript
+import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2'
+
+serve(async (req) => {
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  )
+  // Process request
+  return new Response(JSON.stringify({ success: true }))
+})
+```
+
+---
+
+## Best Practices
+
+Performance: Use HNSW indexes for vectors, Supavisor for connection pooling in serverless
+Security: Always enable RLS, verify JWT tokens, use service_role only in Edge Functions
+Migration: Use Supabase CLI (supabase migration new, supabase db push)
+
+---
+
+## Works Well With
+
+- moai-platform-neon - Alternative PostgreSQL for specific use cases
+- moai-lang-typescript - TypeScript patterns for Supabase client
+- moai-domain-backend - Backend architecture integration
+- moai-foundation-quality - Security and RLS best practices
+- moai-workflow-testing - Test-driven development with Supabase
+
+---
+
+## Module References
+
+For detailed implementation patterns, see the modules directory:
+
+- modules/postgresql-pgvector.md - Complete vector search implementation
+- modules/row-level-security.md - Multi-tenant RLS patterns
+- modules/realtime-presence.md - Real-time collaboration features
+- modules/edge-functions.md - Serverless function patterns
+- modules/storage-cdn.md - File storage and transformations
+- modules/auth-integration.md - Authentication patterns
+- modules/typescript-patterns.md - TypeScript client architecture
+
+For API reference summary, see reference.md
+For full-stack templates, see examples.md
+
+---
+
+Status: Production Ready
+Generated with: MoAI-ADK Skill Factory v2.0
+Last Updated: 2026-01-06
+Version: 2.0.0 (Modularized)
+Coverage: PostgreSQL 16, pgvector, RLS, Real-time, Edge Functions, Storage