moai-adk 0.8.0__py3-none-any.whl → 1.1.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,141 @@
+---
+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.1.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['supabase', 'postgresql', 'pgvector', 'realtime', 'rls', 'edge-functions']
+context7-libraries: ['/supabase/supabase']
+related-skills: ['moai-platform-neon', 'moai-lang-typescript']
+updated: 2026-01-11
+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
+
+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 provides latest PostgreSQL with full SQL support, JSONB, and advanced features.
+
+pgvector Extension enables AI embeddings storage with HNSW and IVFFlat indexes for similarity search.
+
+Row-Level Security provides automatic multi-tenant data isolation at database level.
+
+Real-time Subscriptions enable live data sync via Postgres Changes and Presence.
+
+Edge Functions provide serverless Deno functions at the edge.
+
+Storage provides file storage with automatic image transformations.
+
+Auth provides built-in authentication with JWT integration.
+
+### When to Use Supabase
+
+Use Supabase for multi-tenant SaaS applications requiring data isolation, AI/ML applications needing vector embeddings and similarity search, real-time collaborative features including presence and live updates, full-stack applications needing auth, database, and storage, and 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 include "postgresql pgvector", "row-level-security policies", "realtime subscriptions presence", "edge-functions deno", "storage transformations", and "auth jwt".
+
+---
+
+## Module Index
+
+This skill uses progressive disclosure with specialized modules for detailed implementation patterns.
+
+### Core Modules
+
+postgresql-pgvector covers PostgreSQL 16 with pgvector extension for AI embeddings and semantic search. Topics include vector storage with 1536-dimension OpenAI embeddings, HNSW and IVFFlat index strategies, semantic search functions, and hybrid search combining vector and full-text.
+
+row-level-security covers RLS policies for multi-tenant data isolation. Topics include basic tenant isolation patterns, hierarchical organization access, role-based modification policies, and service role bypass for server operations.
+
+realtime-presence covers real-time subscriptions and presence tracking. Topics include Postgres Changes subscription patterns, filtered change listeners, presence state management, and collaborative cursor and typing indicators.
+
+edge-functions covers serverless Deno functions at the edge. Topics include basic Edge Function with authentication, CORS header configuration, JWT token verification, and rate limiting implementation.
+
+storage-cdn covers file storage with image transformations. Topics include file upload patterns, image transformation URLs, thumbnail generation, and cache control configuration.
+
+auth-integration covers authentication patterns and JWT handling. Topics include server-side client creation, cookie-based session management, auth state synchronization, and protected route patterns.
+
+typescript-patterns covers TypeScript client patterns and service layers. Topics include server-side client for Next.js App Router, service layer abstraction pattern, subscription management, and type-safe database operations.
+
+---
+
+## Quick Start Patterns
+
+### Database Setup
+
+To enable pgvector extension and create embeddings table, execute SQL to create extension vector if not exists. Create a documents table with id as UUID primary key defaulting to gen_random_uuid(), content as TEXT not null, embedding as vector with 1536 dimensions, metadata as JSONB defaulting to empty object, and created_at as TIMESTAMPTZ defaulting to NOW(). Create an index on documents embedding using hnsw with vector_cosine_ops operator class.
+
+### Basic RLS Policy
+
+To create a tenant isolation policy, alter the projects table to enable row level security. Create a policy named "tenant_isolation" on projects for all operations using a condition where tenant_id equals the tenant_id extracted from the auth.jwt() function cast to UUID.
+
+### Real-time Subscription
+
+For real-time subscription, create a channel using supabase.channel with a channel name. Chain the on method for postgres_changes with event set to asterisk for all events, schema set to public, and table set to messages. Provide a callback that logs the payload. Chain subscribe to activate the subscription.
+
+### Edge Function Template
+
+For Edge Function template, import serve from deno.land/std/http/server.ts and createClient from esm.sh/@supabase/supabase-js. Call serve with an async handler that creates a Supabase client using environment variables SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY. Process the request and return a new Response with JSON stringified success object.
+
+---
+
+## Best Practices
+
+Performance: Use HNSW indexes for vectors and Supavisor for connection pooling in serverless environments.
+
+Security: Always enable RLS, verify JWT tokens, and use service_role only in Edge Functions.
+
+Migration: Use Supabase CLI with supabase migration new and supabase db push commands.
+
+---
+
+## Works Well With
+
+- moai-platform-neon for alternative PostgreSQL for specific use cases
+- moai-lang-typescript for TypeScript patterns for Supabase client
+- moai-domain-backend for backend architecture integration
+- moai-foundation-quality for security and RLS best practices
+- moai-workflow-testing for test-driven development with Supabase
+
+---
+
+## Module References
+
+For detailed implementation patterns, see the modules directory:
+
+- modules/postgresql-pgvector.md covers complete vector search implementation
+- modules/row-level-security.md covers multi-tenant RLS patterns
+- modules/realtime-presence.md covers real-time collaboration features
+- modules/edge-functions.md covers serverless function patterns
+- modules/storage-cdn.md covers file storage and transformations
+- modules/auth-integration.md covers authentication patterns
+- modules/typescript-patterns.md covers 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-11
+Version: 2.1.0 (Modularized)
+Coverage: PostgreSQL 16, pgvector, RLS, Real-time, Edge Functions, Storage