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

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

@@ -0,0 +1,322 @@
+# Firestore Reference Documentation
+
+## Data Modeling Best Practices
+
+### Document Structure Guidelines
+
+Flat Data Structures:
+- Firestore charges per document read, not per field
+- Prefer flat structures over deeply nested data
+- Use subcollections for related data that grows unbounded
+
+Denormalization Strategies:
+- Duplicate frequently accessed data to reduce reads
+- Use Cloud Functions to maintain denormalized data consistency
+- Balance read efficiency against write complexity
+
+Document Size Limits:
+- Maximum document size: 1MB
+- Maximum field depth: 20 levels
+- Maximum array elements: 40,000 (practical limit for querying)
+
+### Collection Naming Conventions
+
+Root Collections:
+- Use plural nouns: users, documents, organizations
+- Lowercase with no special characters
+- Keep names short but descriptive
+
+Subcollections:
+- Represent one-to-many relationships
+- Example: /users/{userId}/notifications/{notificationId}
+- Enable collection group queries when needed
+
+---
+
+## Query Optimization
+
+### Index Management
+
+Single-Field Indexes:
+- Automatically created for all fields
+- Support equality and range queries on single fields
+- Ascending and descending variants created automatically
+
+Composite Indexes:
+- Required for queries with multiple equality or range conditions
+- Order matters: equality fields first, then range fields
+- Firebase console shows required indexes in error messages
+
+Index Exemptions:
+- Exclude fields never used in queries
+- Reduce index storage costs
+- Configure in firestore.indexes.json
+
+### Query Performance Tips
+
+Limit Result Sets:
+- Always use limit() to control result size
+- Implement pagination with startAfter() or startAt()
+- Avoid fetching more data than displayed
+
+Cursor-Based Pagination:
+- More efficient than offset-based pagination
+- Use document snapshots as cursors
+- Maintain consistent ordering across pages
+
+Query Constraints:
+- Maximum 30 disjunction clauses (OR conditions)
+- Maximum 10 in/array-contains-any values
+- Range filters on single field only
+
+---
+
+## Security Rules Reference
+
+### Request Object Properties
+
+request.auth:
+- uid: Authenticated user's ID
+- token: JWT claims including custom claims
+- token.email: User's email address
+- token.email_verified: Email verification status
+
+request.resource:
+- data: Document data being written
+- Validate incoming data before write
+
+request.time:
+- Current timestamp for time-based rules
+
+### Resource Object Properties
+
+resource.data:
+- Current document data (for reads/updates/deletes)
+- null for create operations
+
+resource.id:
+- Document ID
+
+resource.__name__:
+- Full document path
+
+### Helper Functions
+
+exists(path):
+- Check if document exists
+- Counts as a read operation
+
+get(path):
+- Retrieve document data
+- Counts as a read operation
+- Maximum 10 get() calls per rule evaluation
+
+getAfter(path):
+- Get document state after batch/transaction
+- Useful for cross-document validation
+
+---
+
+## Cloud Functions Triggers
+
+### Trigger Types
+
+onDocumentCreated:
+- Fires when new document is created
+- Receives snapshot of created document
+
+onDocumentUpdated:
+- Fires when existing document is modified
+- Receives before and after snapshots
+
+onDocumentDeleted:
+- Fires when document is deleted
+- Receives snapshot of deleted document
+
+onDocumentWritten:
+- Fires on any document change (create, update, delete)
+- Most flexible but less specific
+
+### Trigger Best Practices
+
+Idempotency:
+- Design functions to handle duplicate invocations
+- Use document IDs or timestamps for deduplication
+- Store processing state to detect reruns
+
+Error Handling:
+- Return resolved promises for successful operations
+- Throw errors to trigger automatic retry
+- Use dead-letter queues for persistent failures
+
+Performance:
+- Minimize cold start impact with lightweight dependencies
+- Use connection pooling for external services
+- Batch related operations when possible
+
+---
+
+## Offline Behavior
+
+### Cache Behavior
+
+Memory Cache:
+- Fastest access for recently read data
+- Cleared when app closes
+- Configured via memoryLocalCache()
+
+Persistent Cache:
+- Survives app restarts
+- Uses IndexedDB in browsers
+- SQLite on mobile platforms
+
+### Sync Strategies
+
+Automatic Sync:
+- Writes queued when offline
+- Synced automatically on reconnection
+- Order preserved within single client
+
+Conflict Resolution:
+- Last-write-wins for most operations
+- Transactions fail if document changed
+- Use server timestamps for consistent ordering
+
+### Network State Detection
+
+```typescript
+import { onSnapshotsInSync, enableNetwork, disableNetwork } from 'firebase/firestore'
+
+// Detect when all snapshots are synchronized
+onSnapshotsInSync(db, () => {
+  console.log('All snapshots synchronized')
+})
+
+// Programmatically control network state
+await disableNetwork(db)  // Force offline mode
+await enableNetwork(db)   // Resume online operations
+```
+
+---
+
+## Error Handling
+
+### Common Error Codes
+
+permission-denied:
+- Security Rules blocked the operation
+- Check authentication state and rules logic
+
+not-found:
+- Document or collection does not exist
+- Verify path and document ID
+
+already-exists:
+- Attempted to create existing document
+- Use set() with merge option or update()
+
+resource-exhausted:
+- Quota exceeded (reads, writes, or storage)
+- Implement rate limiting or request batching
+
+unavailable:
+- Service temporarily unavailable
+- Implement retry with exponential backoff
+
+### Error Recovery Patterns
+
+```typescript
+import { FirestoreError } from 'firebase/firestore'
+
+async function resilientOperation() {
+  const maxRetries = 3
+  let attempt = 0
+
+  while (attempt < maxRetries) {
+    try {
+      return await performOperation()
+    } catch (error) {
+      if (error instanceof FirestoreError) {
+        if (error.code === 'unavailable') {
+          attempt++
+          await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000))
+          continue
+        }
+      }
+      throw error
+    }
+  }
+}
+```
+
+---
+
+## Migration and Backup
+
+### Data Export
+
+Firebase Console:
+- Export to Cloud Storage bucket
+- Full database or specific collections
+- Scheduled exports available
+
+gcloud CLI:
+```bash
+gcloud firestore export gs://bucket-name/backup-folder
+```
+
+### Data Import
+
+```bash
+gcloud firestore import gs://bucket-name/backup-folder
+```
+
+### Schema Evolution
+
+Adding Fields:
+- New fields can be added without migration
+- Set default values in application code
+- Use Cloud Functions for backfill if needed
+
+Removing Fields:
+- Remove from application code first
+- Clean up existing data with batch operations
+- Update Security Rules to reject old field names
+
+Renaming Fields:
+- Create new field with new name
+- Copy data from old to new field
+- Remove old field after migration complete
+
+---
+
+## Monitoring and Debugging
+
+### Firebase Console Tools
+
+Usage Dashboard:
+- Real-time read/write/delete metrics
+- Storage consumption tracking
+- Quota usage monitoring
+
+Rules Playground:
+- Test Security Rules without deployment
+- Simulate authenticated requests
+- Debug complex rule logic
+
+### Cloud Logging Integration
+
+Enable Logging:
+- Firestore operations logged to Cloud Logging
+- Filter by collection, operation type, or error code
+- Set up alerts for anomalies
+
+Query Debugging:
+- Log slow queries exceeding thresholds
+- Identify missing indexes
+- Track query performance over time
+
+---
+
+Status: Reference Documentation
+Last Updated: 2026-01-06

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

@@ -0,0 +1,156 @@
+---
+name: "moai-platform-neon"
+description: "Neon serverless PostgreSQL specialist covering auto-scaling, database branching, PITR, and connection pooling. Use when building serverless apps needing PostgreSQL, implementing preview environments, or optimizing database costs."
+version: 2.1.0
+category: "platform"
+modularized: true
+user-invocable: false
+tags: ['neon', 'postgresql', 'serverless', 'branching', 'auto-scaling']
+context7-libraries: ['/neondatabase/neon']
+related-skills: ['moai-platform-supabase', 'moai-lang-typescript', 'moai-domain-database']
+updated: 2026-01-11
+status: "active"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# moai-platform-neon: Neon Serverless PostgreSQL Specialist
+
+## Quick Reference
+
+Neon Serverless PostgreSQL Expertise: Specialized knowledge for Neon serverless PostgreSQL covering auto-scaling, scale-to-zero compute, database branching, Point-in-Time Recovery, and modern ORM integration.
+
+### Core Capabilities
+
+Serverless Compute provides auto-scaling PostgreSQL with scale-to-zero for cost optimization.
+
+Database Branching enables instant copy-on-write branches for dev, staging, and preview environments.
+
+Point-in-Time Recovery offers 30-day PITR with instant restore to any timestamp.
+
+Connection Pooling provides built-in connection pooler for serverless and edge compatibility.
+
+PostgreSQL 16 ensures full PostgreSQL 16 compatibility with extensions support.
+
+### Quick Decision Guide
+
+Need serverless PostgreSQL with auto-scaling: Use Neon.
+
+Need database branching for CI/CD: Use Neon branching.
+
+Need edge-compatible database: Use Neon with connection pooling.
+
+Need instant preview environments: Use Neon branch per PR.
+
+Need vector search: Consider Supabase with pgvector instead.
+
+### Context7 Documentation Access
+
+To fetch the latest Neon documentation:
+
+Step 1: Resolve the library ID using mcp__context7__resolve-library-id with library name "neondatabase/neon".
+
+Step 2: Fetch documentation using mcp__context7__get-library-docs with the resolved Context7 ID, specifying topics like "branching", "connection pooling", or "auto-scaling".
+
+---
+
+## Module Index
+
+This skill is organized into focused modules for progressive disclosure:
+
+### Core Modules
+
+Database Branching at modules/branching-workflows.md covers copy-on-write branches for development, preview environments, and CI/CD integration with GitHub Actions.
+
+Auto-Scaling and Compute at modules/auto-scaling.md covers compute unit configuration, scale-to-zero settings, and cost optimization strategies.
+
+Connection Pooling at modules/connection-pooling.md covers serverless connection pooling for edge runtimes, WebSocket configuration, and pool sizing.
+
+PITR and Backups at modules/pitr-backups.md covers point-in-time recovery, branch restoration, and backup strategies.
+
+### Supporting Files
+
+Reference Guide at reference.md provides API reference, environment configuration, and provider comparison.
+
+Code Examples at examples.md provides complete working examples for common integration patterns.
+
+---
+
+## Implementation Guide
+
+### Setup and Configuration
+
+Package Installation requires @neondatabase/serverless from npm. Optionally install drizzle-orm for Drizzle ORM integration or @prisma/client and prisma for Prisma ORM integration.
+
+Environment Configuration requires DATABASE_URL for direct connection used for migrations, formatted as postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require. DATABASE_URL_POOLED provides pooled connection for serverless and edge, formatted as postgresql://user:pass@ep-xxx-pooler.region.neon.tech/dbname?sslmode=require. NEON_API_KEY provides the Neon API key for branching operations. NEON_PROJECT_ID provides the project identifier.
+
+### Serverless Driver Usage
+
+For basic query execution, import neon from @neondatabase/serverless. Create the sql function by calling neon with the DATABASE_URL environment variable. Execute simple queries using tagged template literals with the sql function. For parameterized queries that are SQL injection safe, include variables inside the template literal. The driver supports transaction operations using sql.transaction with an array of SQL statements.
+
+### Drizzle ORM Integration
+
+For schema definition, import table and column types from drizzle-orm/pg-core. Define tables using pgTable with column definitions. Use uuid for UUIDs with primaryKey and defaultRandom, text for strings with notNull and unique modifiers, timestamp for dates with defaultNow, and jsonb for JSON columns.
+
+For Drizzle client setup, import neon from @neondatabase/serverless, drizzle from drizzle-orm/neon-http, and the schema module. Create the sql function with neon and the DATABASE_URL. Export the db instance created with drizzle passing sql and the schema. Execute queries using db.select().from(schema.tableName).
+
+### Prisma ORM Integration
+
+For Prisma with Neon Serverless Driver, import Pool and neonConfig from @neondatabase/serverless, PrismaNeon from @prisma/adapter-neon, and PrismaClient from @prisma/client. Set neonConfig.webSocketConstructor to the ws module. Create a Pool with the DATABASE_URL connection string. Create an adapter with PrismaNeon passing the pool. Export the prisma instance created with PrismaClient passing the adapter.
+
+---
+
+## Provider Decision Guide
+
+### When to Use Neon
+
+Serverless Applications benefit from auto-scaling and scale-to-zero that reduce costs significantly.
+
+Preview Environments benefit from instant branching that enables per-PR databases with production data.
+
+Edge Deployment benefits from connection pooling that provides edge runtime compatibility.
+
+Development Workflow benefits from branching from production for realistic development data.
+
+Cost Optimization benefits from paying only for active compute time with scale-to-zero.
+
+### When to Consider Alternatives
+
+Need Vector Search: Consider Supabase with pgvector or dedicated vector database.
+
+Need Real-time Subscriptions: Consider Supabase or Convex for real-time features.
+
+Need NoSQL Flexibility: Consider Firestore or Convex for document storage.
+
+Need Built-in Auth: Consider Supabase for integrated authentication.
+
+### Pricing Reference
+
+Free Tier provides 3GB storage and 100 compute hours per month.
+
+Pro Tier provides usage-based pricing with additional storage and compute.
+
+Scale-to-Zero incurs no charges during idle periods.
+
+---
+
+## Works Well With
+
+- moai-platform-supabase for alternative when RLS or pgvector needed
+- moai-lang-typescript for TypeScript patterns for Drizzle and Prisma
+- moai-domain-backend for backend architecture with database integration
+- moai-domain-database for general database patterns and optimization
+
+---
+
+Status: Production Ready
+Version: 2.1.0
+Generated with: MoAI-ADK Skill Factory v2.0
+Last Updated: 2026-01-11
+Technology: Neon Serverless PostgreSQL