lua-cli 2.5.7 → 3.0.0-alpha.1

package/template/package.json

@@ -19,7 +19,7 @@
     "axios": "^1.6.0",
     "inquirer": "^12.9.6",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^2.5.6",
+    "lua-cli": "^2.5.8",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"

package/template/src/index-agent-example.ts

@@ -0,0 +1,201 @@
+// /**
+//  * LuaAgent Example - Simplified Agent Configuration
+//  * 
+//  * This example shows the NEW, RECOMMENDED way to define your agent using LuaAgent.
+//  * Instead of exporting individual skills, webhooks, jobs, and processors,
+//  * you create one unified LuaAgent object that contains everything.
+//  * 
+//  * Benefits:
+//  * - Simpler, cleaner code
+//  * - All configuration in one place
+//  * - Easier to understand and maintain
+//  * - Agent persona is synced with lua.skill.yaml automatically
+//  */
+
+// import { LuaAgent, LuaSkill } from "lua-cli";
+// import GetWeatherTool from "./tools/GetWeatherTool";
+// import { GetUserDataTool, UpdateUserDataTool } from "./tools/UserDataTool";
+// import CreatePostTool from "./tools/CreatePostTool";
+// import { SearchProductsTool, CreateProductTool, UpdateProductTool, GetAllProductsTool, GetProductByIdTool, DeleteProductTool } from "./tools/ProductsTool";
+// import { CreateBasketTool, GetBasketsTool, AddItemToBasketTool, RemoveItemFromBasketTool, ClearBasketTool, UpdateBasketStatusTool, UpdateBasketMetadataTool, CheckoutBasketTool, GetBasketByIdTool } from "./tools/BasketTool";
+// import { CreateOrderTool, UpdateOrderStatusTool, GetOrderByIdTool, GetUserOrdersTool } from "./tools/OrderTool";
+// import { CreateMovieTool, GetMoviesTool, GetMovieByIdTool, UpdateMovieTool, SearchMoviesTool, DeleteMovieTool } from "./tools/CustomDataTool";
+
+// // ============================================================================
+// // WEBHOOK EXAMPLES (Uncomment to enable)
+// // ============================================================================
+// // import userEventWebhook from "./webhooks/UserEventWebhook";
+// // import paymentWebhook from "./webhooks/PaymentWebhook";
+
+// // ============================================================================
+// // JOB EXAMPLES (Uncomment to enable)
+// // ============================================================================
+// // import dailyCleanupJob from "./jobs/DailyCleanupJob";
+// // import healthCheckJob from "./jobs/HealthCheckJob";
+
+// // ============================================================================
+// // PREPROCESSOR/POSTPROCESSOR EXAMPLES
+// // ============================================================================
+// import messageFilter from "./preprocessors/MessageFilter";
+// import responseFormatter from "./postprocessors/ResponseFormatter";
+
+// // ============================================================================
+// // SKILLS
+// // ============================================================================
+
+// // Skills can be defined separately for better organization
+// const generalSkill = new LuaSkill({
+//   name: "general-skill",
+//   version: "1.0.0",
+//   description: "General utilities including weather and post creation",
+//   context: "This skill provides weather information and post creation capabilities.",
+//   tools: [
+//     new GetWeatherTool(),
+//     new CreatePostTool()
+//   ]
+// });
+
+// const userDataSkill = new LuaSkill({
+//   name: "user-data-skill",
+//   version: "1.0.0",
+//   description: "User data management",
+//   context: "This skill provides user data retrieval and update capabilities.",
+//   tools: [
+//     new GetUserDataTool(),
+//     new UpdateUserDataTool()
+//   ]
+// });
+
+// const productSkill = new LuaSkill({
+//   name: "product-skill",
+//   version: "1.0.0",
+//   description: "Product catalog management",
+//   context: "This skill provides comprehensive product management capabilities.",
+//   tools: [
+//     new SearchProductsTool(),
+//     new GetAllProductsTool(),
+//     new CreateProductTool(),
+//     new UpdateProductTool(),
+//     new GetProductByIdTool(),
+//     new DeleteProductTool()
+//   ]
+// });
+
+// const basketSkill = new LuaSkill({
+//   name: "basket-skill",
+//   version: "1.0.0",
+//   description: "Shopping basket management",
+//   context: "This skill provides shopping basket operations.",
+//   tools: [
+//     new CreateBasketTool(),
+//     new GetBasketsTool(),
+//     new AddItemToBasketTool(),
+//     new RemoveItemFromBasketTool(),
+//     new ClearBasketTool(),
+//     new UpdateBasketStatusTool(),
+//     new UpdateBasketMetadataTool(),
+//     new CheckoutBasketTool(),
+//     new GetBasketByIdTool()
+//   ]
+// });
+
+// const orderSkill = new LuaSkill({
+//   name: "order-skill",
+//   version: "1.0.0",
+//   description: "Order management",
+//   context: "This skill provides order management capabilities.",
+//   tools: [
+//     new CreateOrderTool(),
+//     new UpdateOrderStatusTool(),
+//     new GetOrderByIdTool(),
+//     new GetUserOrdersTool()
+//   ]
+// });
+
+// const customDataSkill = new LuaSkill({
+//   name: "custom-data-skill",
+//   version: "1.0.0",
+//   description: "Custom data management for movies",
+//   context: "This skill provides custom data storage and retrieval for movies.",
+//   tools: [
+//     new CreateMovieTool(),
+//     new GetMoviesTool(),
+//     new GetMovieByIdTool(),
+//     new UpdateMovieTool(),
+//     new SearchMoviesTool(),
+//     new DeleteMovieTool()
+//   ]
+// });
+
+// // ============================================================================
+// // AGENT CONFIGURATION (NEW APPROACH)
+// // ============================================================================
+
+// /**
+//  * This is the main agent configuration.
+//  * The LuaAgent consolidates everything in one place:
+//  * - Agent persona (behavior and personality)
+//  * - Skills (collections of tools)
+//  * - Webhooks (HTTP endpoints)
+//  * - Jobs (scheduled tasks)
+//  * - PreProcessors (run before messages reach agent)
+//  * - PostProcessors (run after agent generates responses)
+//  * 
+//  * The compiler will:
+//  * 1. Detect this LuaAgent
+//  * 2. Extract all components (skills, webhooks, jobs, processors)
+//  * 3. Sync the persona with lua.skill.yaml
+//  * 4. Deploy everything to the Lua platform
+//  */
+// export const agent = new LuaAgent({
+//   name: "my-assistant",
+//   persona: `You are a helpful e-commerce assistant that can help users with:
+//     - Weather information
+//     - User account management
+//     - Product browsing and search
+//     - Shopping basket operations
+//     - Order management
+//     - Movie database management
+    
+//     You are friendly, helpful, and provide clear responses. When users ask about products,
+//     help them search and find what they need. When they want to purchase, guide them through
+//     the basket and checkout process.`,
+  
+//   welcomeMessage: "Hello! I'm your e-commerce assistant. I can help you find products, manage your basket, and track orders. How can I help you today?",
+  
+//   // Add all your skills here
+//   skills: [
+//     generalSkill,
+//     userDataSkill,
+//     productSkill,
+//     basketSkill,
+//     orderSkill,
+//     customDataSkill
+//   ],
+  
+//   // Uncomment to add webhooks
+//   // webhooks: [
+//   //   userEventWebhook,
+//   //   paymentWebhook
+//   // ],
+  
+//   // Uncomment to add scheduled jobs
+//   // jobs: [
+//   //   dailyCleanupJob,
+//   //   healthCheckJob
+//   // ],
+  
+//   // Message preprocessors (filter spam, add context, etc.)
+//   preProcessors: [
+//     messageFilter
+//   ],
+  
+//   // Response postprocessors (format output, add branding, etc.)
+//   postProcessors: [
+//     responseFormatter
+//   ]
+// });
+
+// // That's it! The compiler will detect this LuaAgent and deploy everything.
+// // No need to export individual skills, webhooks, jobs, etc.
+

package/template/src/index.ts

@@ -8,6 +8,45 @@ import { CreateBasketTool, GetBasketsTool, AddItemToBasketTool, RemoveItemFromBa
 import { CreateOrderTool, UpdateOrderStatusTool, GetOrderByIdTool, GetUserOrdersTool } from "./tools/OrderTool";
 import { CreateMovieTool, GetMoviesTool, GetMovieByIdTool, UpdateMovieTool, SearchMoviesTool, DeleteMovieTool } from "./tools/CustomDataTool";
 
+// ============================================================================
+// WEBHOOK EXAMPLES (Uncomment to enable)
+// ============================================================================
+// Webhooks receive HTTP requests from external systems
+// See: WEBHOOK_JOB_EXAMPLES.md for detailed explanations
+
+// import userEventWebhook from "./webhooks/UserEventWebhook";
+// import paymentWebhook from "./webhooks/PaymentWebhook";
+
+// ============================================================================
+// JOB EXAMPLES (Uncomment to enable)
+// ============================================================================
+// Jobs are scheduled tasks that run at specific times or intervals
+// See: WEBHOOK_JOB_EXAMPLES.md for detailed explanations
+
+// import dailyCleanupJob from "./jobs/DailyCleanupJob";
+// import healthCheckJob from "./jobs/HealthCheckJob";
+// import dataMigrationJob from "./jobs/DataMigrationJob";
+// import abandonedBasketProcessorJob from "./jobs/AbandonedBasketProcessorJob";
+
+// ============================================================================
+// SMART BASKET TOOL (Uncomment to enable)
+// ============================================================================
+// This tool creates baskets with automatic abandoned cart reminders
+// Uses Jobs.create() to schedule one-time check 3 hours after creation
+
+// import { CreateSmartBasketTool, CheckAbandonedBasketsTool } from "./tools/SmartBasketTool";
+
+// ============================================================================
+// GAME SCORE TRACKER (Uncomment to enable) - ADVANCED EXAMPLE
+// ============================================================================
+// Complex example showing:
+// - Interval jobs that start at specific time
+// - Jobs that stop themselves when condition is met
+// - Real-time monitoring with external API integration
+// See: COMPLEX_JOB_EXAMPLES.md for detailed explanation
+
+// import { TrackGameScoresTool, GetGameScoresTool, StopGameTrackingTool } from "./tools/GameScoreTrackerTool";
+
 
 // Initialize skill with tools
 const generalSkill = new LuaSkill({

package/template/src/jobs/AbandonedBasketProcessorJob.ts

@@ -0,0 +1,139 @@
+/**
+ * Abandoned Basket Processor Job
+ * 
+ * This job runs every 15 minutes to process basket checkout reminders.
+ * Works together with CreateSmartBasketTool to send abandoned cart notifications.
+ * 
+ * Flow:
+ * 1. User creates basket → Tool schedules reminder in custom data
+ * 2. This job runs every 15 minutes
+ * 3. Checks which reminders are due
+ * 4. Checks if baskets were checked out
+ * 5. Sends reminders for abandoned baskets
+ */
+
+import { LuaJob, Data, Baskets } from "lua-cli";
+
+const abandonedBasketProcessorJob = new LuaJob({
+  name: "process-basket-reminders",
+  version: "1.0.0",
+  description: "Processes abandoned basket reminders",
+  context: "Runs every 15 minutes to check for abandoned baskets and send recovery emails. " +
+           "Works with basket creation tools that schedule reminders.",
+
+  // Run every 15 minutes
+  schedule: {
+    type: 'interval',
+    seconds: 900  // 15 minutes = 900 seconds
+  },
+
+  timeout: 120,  // 2 minutes
+
+  execute: async () => {
+    console.log('🔍 Processing basket reminders...');
+
+    // Get all pending reminders
+    const remindersResponse = await Data.get('basket-reminders', {}, 1, 500);
+    const reminders = remindersResponse.data || [];
+    const now = new Date();
+
+    let processedCount = 0;
+    let abandonedCount = 0;
+    let checkedOutCount = 0;
+
+    for (const reminder of reminders) {
+      // Skip if not yet time
+      const scheduledTime = new Date(reminder.data.scheduledFor);
+      if (scheduledTime > now) continue;
+
+      // Skip if already processed
+      if (reminder.data.status !== 'pending') continue;
+
+      try {
+        // Get the basket
+        const basketInstance = await Baskets.getById(reminder.data.basketId);
+        const basket = await basketInstance.getData();
+
+        // Check basket status
+        const isAbandoned = basket.status === 'active';
+
+        if (isAbandoned) {
+          // Basket is abandoned - send reminder
+          console.log(`🛒 Abandoned basket found: ${basket.id}`);
+          abandonedCount++;
+
+          // Calculate basket value
+          const totalValue = basket.items?.reduce((sum: number, item: any) => {
+            return sum + (item.price * item.quantity);
+          }, 0) || 0;
+
+          // Log abandoned basket
+          await Data.create('abandoned-baskets', {
+            basketId: basket.id,
+            currency: basket.currency,
+            itemCount: basket.items?.length || 0,
+            totalValue,
+            items: basket.items,
+            abandonedAt: new Date().toISOString(),
+            reminderSent: true
+          });
+
+          // Update reminder status
+          await Data.update('basket-reminders', reminder.id, {
+            ...reminder.data,
+            status: 'completed',
+            result: 'abandoned',
+            processedAt: new Date().toISOString()
+          });
+
+          // TODO: Send actual reminder email/SMS
+          console.log(`📧 Would send reminder: "You left ${basket.items?.length || 0} items in your cart!"`);
+
+        } else {
+          // Basket was checked out
+          console.log(`✅ Basket ${basket.id} was checked out (${basket.status})`);
+          checkedOutCount++;
+
+          // Update reminder status
+          await Data.update('basket-reminders', reminder.id, {
+            ...reminder.data,
+            status: 'completed',
+            result: 'checked-out',
+            processedAt: new Date().toISOString()
+          });
+        }
+
+        processedCount++;
+
+      } catch (error) {
+        console.error(`❌ Error processing basket ${reminder.data.basketId}:`, error);
+        
+        // Mark as error
+        try {
+          await Data.update('basket-reminders', reminder.id, {
+            ...reminder.data,
+            status: 'error',
+            error: String(error),
+            processedAt: new Date().toISOString()
+          });
+        } catch (updateError) {
+          console.error('Failed to update reminder status:', updateError);
+        }
+      }
+    }
+
+    console.log('✅ Reminder processing complete');
+    console.log(`📊 Processed: ${processedCount}, Abandoned: ${abandonedCount}, Checked out: ${checkedOutCount}`);
+
+    return {
+      success: true,
+      processedCount,
+      abandonedCount,
+      checkedOutCount,
+      timestamp: new Date().toISOString()
+    };
+  }
+});
+
+export default abandonedBasketProcessorJob;
+

package/template/src/jobs/DailyCleanupJob.ts

@@ -0,0 +1,100 @@
+/**
+ * Daily Cleanup Job Example
+ * 
+ * This job runs daily at 2 AM to clean up old data and maintain database performance.
+ * Demonstrates: Cron scheduling, data cleanup, and error handling.
+ */
+
+import { LuaJob, Data } from "lua-cli";
+
+const dailyCleanupJob = new LuaJob({
+  name: "daily-cleanup",
+  version: "1.0.0",
+  description: "Daily database cleanup and maintenance",
+  context: "Runs at 2 AM EST daily to remove old logs, expired sessions, and optimize data collections. " +
+           "This job helps maintain database performance and storage costs.",
+
+  // Cron schedule: Every day at 2 AM EST
+  schedule: {
+    type: 'cron',
+    expression: '0 2 * * *',  // minute hour day month day-of-week
+    timezone: 'America/New_York'
+  },
+
+  // Give it 10 minutes to complete
+  timeout: 600,
+
+  // Retry up to 3 times if it fails
+  retry: {
+    maxAttempts: 3,
+    backoffSeconds: 60  // Wait 60s between retries
+  },
+
+  execute: async () => {
+    console.log('🧹 Starting daily cleanup...');
+    const startTime = Date.now();
+
+    let totalRecordsDeleted = 0;
+
+    // 1. Clean up old user events (older than 90 days)
+    const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
+    
+    try {
+      const oldEventsResponse = await Data.get('user-events', {}, 1, 1000);
+      const oldEvents = oldEventsResponse.data || [];
+      
+      for (const event of oldEvents) {
+        const eventDate = new Date(event.data.receivedAt);
+        if (eventDate < ninetyDaysAgo) {
+          await Data.delete('user-events', event.id);
+          totalRecordsDeleted++;
+        }
+      }
+      
+      console.log(`✅ Deleted ${totalRecordsDeleted} old user events`);
+    } catch (error) {
+      console.error('❌ Error cleaning user events:', error);
+    }
+
+    // 2. Clean up old payment logs (older than 180 days)
+    const oneEightyDaysAgo = new Date(Date.now() - 180 * 24 * 60 * 60 * 1000);
+    
+    try {
+      const oldLogsResponse = await Data.get('payment-logs', {}, 1, 1000);
+      const oldLogs = oldLogsResponse.data || [];
+      let logsDeleted = 0;
+      
+      for (const log of oldLogs) {
+        const logDate = new Date(log.data.receivedAt);
+        if (logDate < oneEightyDaysAgo) {
+          await Data.delete('payment-logs', log.id);
+          logsDeleted++;
+          totalRecordsDeleted++;
+        }
+      }
+      
+      console.log(`✅ Deleted ${logsDeleted} old payment logs`);
+    } catch (error) {
+      console.error('❌ Error cleaning payment logs:', error);
+    }
+
+    // 3. Clean up abandoned baskets (older than 7 days)
+    // Note: This would require basket API support for deletion
+    // For now, we'll just log the count
+    
+    const duration = Date.now() - startTime;
+    
+    console.log(`✅ Cleanup complete in ${duration}ms`);
+
+    return {
+      success: true,
+      recordsDeleted: totalRecordsDeleted,
+      duration: `${duration}ms`,
+      completedAt: new Date().toISOString(),
+      collections: ['user-events', 'payment-logs']
+    };
+  }
+});
+
+export default dailyCleanupJob;
+

package/template/src/jobs/DataMigrationJob.ts

@@ -0,0 +1,133 @@
+/**
+ * Data Migration Job Example
+ * 
+ * This is a one-time job that runs at a specific date/time to migrate data.
+ * Demonstrates: One-time scheduling, data migration, and batch processing.
+ */
+
+import { LuaJob, Data } from "lua-cli";
+
+const dataMigrationJob = new LuaJob({
+  name: "migrate-user-schema",
+  version: "1.0.0",
+  description: "One-time migration to new user event schema",
+  context: "Scheduled one-time task to migrate user events from old schema to new schema. " +
+           "Runs once at the specified time and then automatically deactivates.",
+
+  // One-time schedule: Run at specific date/time
+  schedule: {
+    type: 'once',
+    executeAt: new Date('2025-12-31T02:00:00Z')  // December 31, 2025 at 2 AM UTC
+  },
+
+  // Give it 30 minutes for large migration
+  timeout: 1800,
+
+  // Retry important migrations
+  retry: {
+    maxAttempts: 3,
+    backoffSeconds: 300  // 5 minutes between retries
+  },
+
+  execute: async () => {
+    console.log('🔄 Starting data migration...');
+    const startTime = Date.now();
+
+    let totalMigrated = 0;
+    let totalErrors = 0;
+
+    try {
+      // Get all user events with old schema
+      const oldEventsResponse = await Data.get('user-events', {}, 1, 1000);
+      const oldEvents = oldEventsResponse.data || [];
+      
+      console.log(`📊 Found ${oldEvents.length} events to migrate`);
+
+      // Migrate each event
+      for (const event of oldEvents) {
+        try {
+          // Transform old schema to new schema
+          const migratedEvent = {
+            // New fields
+            eventId: event.id,
+            eventType: event.data.type || 'unknown',
+            userId: event.data.userId || event.data.user_id,  // Handle both formats
+            email: event.data.email,
+            name: event.data.name,
+            
+            // Preserve metadata
+            metadata: {
+              ...event.data.metadata,
+              migratedFrom: 'old-schema',
+              migratedAt: new Date().toISOString()
+            },
+            
+            // Copy timestamps
+            originalTimestamp: event.data.timestamp,
+            receivedAt: event.data.receivedAt
+          };
+
+          // Create in new collection
+          await Data.create('user-events-v2', migratedEvent, 
+            `${migratedEvent.eventType} ${migratedEvent.email}`
+          );
+
+          totalMigrated++;
+
+          // Log progress every 100 records
+          if (totalMigrated % 100 === 0) {
+            console.log(`✅ Migrated ${totalMigrated} records...`);
+          }
+
+        } catch (error) {
+          console.error(`❌ Failed to migrate event ${event.id}:`, error);
+          totalErrors++;
+        }
+      }
+
+      const duration = Date.now() - startTime;
+      const successRate = ((totalMigrated / oldEvents.length) * 100).toFixed(2);
+
+      console.log(`✅ Migration complete!`);
+      console.log(`📊 Stats:`);
+      console.log(`   - Total records: ${oldEvents.length}`);
+      console.log(`   - Migrated: ${totalMigrated}`);
+      console.log(`   - Errors: ${totalErrors}`);
+      console.log(`   - Success rate: ${successRate}%`);
+      console.log(`   - Duration: ${duration}ms`);
+
+      // Store migration report
+      await Data.create('migration-reports', {
+        jobName: 'migrate-user-schema',
+        totalRecords: oldEvents.length,
+        migrated: totalMigrated,
+        errors: totalErrors,
+        successRate: parseFloat(successRate),
+        duration,
+        completedAt: new Date().toISOString()
+      });
+
+      return {
+        success: true,
+        totalRecords: oldEvents.length,
+        migrated: totalMigrated,
+        errors: totalErrors,
+        successRate: `${successRate}%`,
+        duration: `${duration}ms`
+      };
+
+    } catch (error) {
+      console.error('💥 Migration failed:', error);
+      
+      return {
+        success: false,
+        error: String(error),
+        totalMigrated,
+        totalErrors
+      };
+    }
+  }
+});
+
+export default dataMigrationJob;
+