moai-adk 0.32.8__py3-none-any.whl → 0.41.2__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,206 @@
+---
+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.0.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-08
+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: Auto-scaling PostgreSQL with scale-to-zero for cost optimization
+Database Branching: Instant copy-on-write branches for dev, staging, and preview environments
+Point-in-Time Recovery: 30-day PITR with instant restore to any timestamp
+Connection Pooling: Built-in connection pooler for serverless and edge compatibility
+PostgreSQL 16: 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](modules/branching-workflows.md): Copy-on-write branches for development, preview environments, and CI/CD integration with GitHub Actions
+
+[Auto-Scaling and Compute](modules/auto-scaling.md): Compute unit configuration, scale-to-zero settings, and cost optimization strategies
+
+[Connection Pooling](modules/connection-pooling.md): Serverless connection pooling for edge runtimes, WebSocket configuration, and pool sizing
+
+[PITR and Backups](modules/pitr-backups.md): Point-in-time recovery, branch restoration, and backup strategies
+
+### Supporting Files
+
+[Reference Guide](reference.md): API reference, environment configuration, and provider comparison
+
+[Code Examples](examples.md): Complete working examples for common integration patterns
+
+---
+
+## Implementation Guide
+
+### Setup and Configuration
+
+Package Installation:
+```bash
+npm install @neondatabase/serverless
+npm install drizzle-orm  # Optional: Drizzle ORM
+npm install @prisma/client prisma  # Optional: Prisma ORM
+```
+
+Environment Configuration:
+```env
+# Direct connection (for migrations)
+DATABASE_URL=postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require
+
+# Pooled connection (for serverless/edge)
+DATABASE_URL_POOLED=postgresql://user:pass@ep-xxx-pooler.region.neon.tech/dbname?sslmode=require
+
+# Neon API for branching
+NEON_API_KEY=neon_api_key_xxx
+NEON_PROJECT_ID=project-xxx
+```
+
+### Serverless Driver Usage
+
+Basic Query Execution:
+```typescript
+import { neon } from '@neondatabase/serverless'
+
+const sql = neon(process.env.DATABASE_URL!)
+
+// Simple query
+const users = await sql`SELECT * FROM users WHERE active = true`
+
+// Parameterized query (SQL injection safe)
+const userId = 'user-123'
+const user = await sql`SELECT * FROM users WHERE id = ${userId}`
+
+// Transaction support
+const result = await sql.transaction([
+  sql`UPDATE accounts SET balance = balance - 100 WHERE id = ${fromId}`,
+  sql`UPDATE accounts SET balance = balance + 100 WHERE id = ${toId}`
+])
+```
+
+### Drizzle ORM Integration
+
+Schema Definition:
+```typescript
+import { pgTable, uuid, text, timestamp, boolean, jsonb } from 'drizzle-orm/pg-core'
+
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: text('email').notNull().unique(),
+  name: text('name'),
+  createdAt: timestamp('created_at').defaultNow(),
+  metadata: jsonb('metadata')
+})
+```
+
+Drizzle Client Setup:
+```typescript
+import { neon } from '@neondatabase/serverless'
+import { drizzle } from 'drizzle-orm/neon-http'
+import * as schema from './schema'
+
+const sql = neon(process.env.DATABASE_URL!)
+export const db = drizzle(sql, { schema })
+
+// Query examples
+const allUsers = await db.select().from(schema.users)
+```
+
+### Prisma ORM Integration
+
+Prisma with Neon Serverless Driver:
+```typescript
+import { Pool, neonConfig } from '@neondatabase/serverless'
+import { PrismaNeon } from '@prisma/adapter-neon'
+import { PrismaClient } from '@prisma/client'
+
+neonConfig.webSocketConstructor = require('ws')
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL })
+const adapter = new PrismaNeon(pool)
+export const prisma = new PrismaClient({ adapter })
+```
+
+---
+
+## Provider Decision Guide
+
+### When to Use Neon
+
+Serverless Applications: Auto-scaling and scale-to-zero reduce costs significantly
+Preview Environments: Instant branching enables per-PR databases with production data
+Edge Deployment: Connection pooling provides edge runtime compatibility
+Development Workflow: Branch from production for realistic development data
+Cost Optimization: Pay 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: 3GB storage, 100 compute hours per month
+Pro Tier: Usage-based pricing with additional storage and compute
+Scale-to-Zero: No charges during idle periods
+
+---
+
+## Works Well With
+
+- moai-platform-supabase - Alternative when RLS or pgvector needed
+- moai-lang-typescript - TypeScript patterns for Drizzle and Prisma
+- moai-domain-backend - Backend architecture with database integration
+- moai-domain-database - General database patterns and optimization
+
+---
+
+Status: Production Ready
+Version: 2.0.0
+Generated with: MoAI-ADK Skill Factory v2.0
+Last Updated: 2026-01-06
+Technology: Neon Serverless PostgreSQL