lua-cli 3.0.0-alpha.1 → 3.0.0-alpha.5

package/template/COMPLEX_JOB_EXAMPLES.md

@@ -1,795 +0,0 @@
-# Complex Job Example: Game Score Tracker
-
-**Level**: Advanced  
-**Demonstrates**: Interval jobs, self-termination, dynamic job creation, real-time monitoring
-
----
-
-## 🎯 What It Does
-
-A complete system for tracking live game scores that:
-1. ✅ Creates a game tracking record
-2. ✅ Creates an interval job that starts at game time
-3. ✅ Fetches score updates every X seconds
-4. ✅ Checks if game is over
-5. ✅ **Stops itself** when game ends
-6. ✅ Logs final results
-
-**Perfect for**: Sports scores, esports matches, auctions, stock monitoring, server status
-
----
-
-## 📁 Files
-
-**Location**: `src/tools/GameScoreTrackerTool.ts`
-
-**Contains 3 tools:**
-1. `TrackGameScoresTool` - Start tracking a game
-2. `GetGameScoresTool` - Get current scores
-3. `StopGameTrackingTool` - Manually stop tracking
-
----
-
-## 🎮 The Flow
-
-### User Perspective
-
-```
-User: "Track the Lakers vs Warriors game starting at 7 PM"
-        ↓
-Agent uses: track_game_scores
-        ↓
-Tool creates:
-  - Game record in database
-  - Interval job (updates every 60 seconds)
-        ↓
-Job starts at 7 PM
-        ↓
-Every 60 seconds, job:
-  1. Fetches latest scores
-  2. Updates database
-  3. Checks if game finished
-        ↓
-When game ends:
-  - Job logs final score
-  - Job deactivates itself ⭐
-  - Tracking stops automatically
-```
-
----
-
-## 💻 Code Walkthrough
-
-### Part 1: Create Game Record
-
-```typescript
-async execute(input: {
-  gameId: string;
-  gameName: string;
-  startTime: string;
-  updateIntervalSeconds: number;
-}) {
-  // Create game record
-  const gameRecord = {
-    gameId: input.gameId,
-    gameName: input.gameName,
-    startTime: input.startTime,
-    status: 'scheduled',
-    currentScore: { home: 0, away: 0 },
-    createdAt: new Date().toISOString()
-  };
-
-  const game = await Data.create('games', gameRecord);
-  console.log(`✅ Game record created: ${game.id}`);
-```
-
-### Part 2: Calculate Start Time
-
-```typescript
-  // Calculate when job should start
-  const gameStartTime = new Date(input.startTime);
-  const now = new Date();
-
-  // If game hasn't started, wait until start time
-  // If already started, begin immediately
-  const jobStartTime = gameStartTime > now ? gameStartTime : now;
-
-  console.log(`⏰ Job will start at: ${jobStartTime.toLocaleString()}`);
-```
-
-**Key insight**: Job can be created now but scheduled to start later!
-
-### Part 3: Capture Variables for Closure
-
-```typescript
-  // Capture for job closure
-  const gameId = input.gameId;
-  const gameName = input.gameName;
-  const intervalSeconds = input.updateIntervalSeconds;
-  const apiEndpoint = input.apiEndpoint || 'https://api.example.com/scores';
-  const gameRecordId = game.id;
-```
-
-### Part 4: Create Self-Terminating Interval Job
-
-```typescript
-  const job = await Jobs.create({
-    name: `track-game-${gameId}`,
-    description: `Live score tracking for ${gameName}`,
-    
-    // Interval job - runs every X seconds
-    schedule: {
-      type: 'interval',
-      seconds: intervalSeconds
-    },
-    
-    timeout: 30,
-    retry: { maxAttempts: 2, backoffSeconds: 10 },
-    
-    execute: async () => {
-      console.log(`🎮 Fetching score update for ${gameId}...`);
-      
-      // 1. Get current game data
-      const gameData = await Data.getEntry('games', gameRecordId);
-      
-      // 2. Check if already finished
-      if (gameData.data.status === 'finished') {
-        console.log(`🏁 Game ${gameId} finished. Stopping job.`);
-        
-        // ⭐ KEY FEATURE: Job stops itself!
-        await Jobs.deactivate(job.jobId);
-        
-        return {
-          action: 'job-stopped',
-          reason: 'game-finished',
-          finalScore: gameData.data.currentScore
-        };
-      }
-      
-      // 3. Fetch latest scores from API
-      const response = await fetch(`${apiEndpoint}/${gameId}`);
-      const scoreUpdate = await response.json();
-      
-      // 4. Update database
-      await Data.update('games', gameRecordId, {
-        ...gameData.data,
-        currentScore: {
-          home: scoreUpdate.home,
-          away: scoreUpdate.away
-        },
-        quarter: scoreUpdate.quarter,
-        status: scoreUpdate.isFinished ? 'finished' : 'in-progress',
-        lastUpdate: new Date().toISOString()
-      });
-      
-      console.log(`📊 Score: ${scoreUpdate.home} - ${scoreUpdate.away}`);
-      
-      // 5. If game just ended, stop the job
-      if (scoreUpdate.isFinished) {
-        console.log(`🏁 Game ${gameId} ended!`);
-        
-        // Store final result
-        await Data.create('game-results', {
-          gameId: gameId,
-          finalScore: scoreUpdate,
-          finishedAt: new Date().toISOString()
-        });
-        
-        // ⭐ Stop the job!
-        await Jobs.deactivate(job.jobId);
-        
-        return {
-          action: 'game-ended-job-stopped',
-          finalScore: scoreUpdate
-        };
-      }
-      
-      // Game still in progress
-      return {
-        action: 'score-updated',
-        currentScore: scoreUpdate
-      };
-    }
-  });
-
-  return {
-    success: true,
-    game,
-    scoreTracker: {
-      jobId: job.jobId,
-      updateInterval: intervalSeconds
-    }
-  };
-}
-```
-
----
-
-## 🔑 Key Concepts
-
-### 1. **Self-Terminating Job**
-
-The job can deactivate itself:
-
-```typescript
-execute: async () => {
-  // Check condition
-  if (gameIsOver) {
-    // Stop myself!
-    await Jobs.deactivate(job.jobId);
-    return { action: 'stopped' };
-  }
-  
-  // Continue running
-  return { action: 'continue' };
-}
-```
-
-**How it works:**
-- Job has access to `Jobs` API in sandbox
-- Job can call `Jobs.deactivate(job.jobId)`
-- Closure captures `job.jobId` from parent scope
-- Job stops scheduling future executions
-
-### 2. **Interval Jobs with Start Time**
-
-```typescript
-// Job created now
-const job = await Jobs.create({
-  schedule: {
-    type: 'interval',
-    seconds: 60  // Every 60 seconds
-  }
-});
-
-// But starts at specific time (gameStartTime)
-// Backend scheduler waits until start time, then begins interval
-```
-
-### 3. **Closure Capture**
-
-```typescript
-const gameId = 'game_123';
-const apiEndpoint = 'https://api.example.com';
-
-execute: async () => {
-  // These variables are captured!
-  const response = await fetch(`${apiEndpoint}/${gameId}`);
-  //                             ↑            ↑
-  //                        Both available!
-}
-```
-
-### 4. **Error Handling Without Stopping**
-
-```typescript
-execute: async () => {
-  try {
-    // Try to fetch from external API
-    const response = await fetch(apiEndpoint);
-    const data = await response.json();
-  } catch (error) {
-    console.error('API failed:', error);
-    
-    // Don't stop job - just log error and continue
-    return { action: 'error', error: error.message };
-  }
-}
-```
-
-Job continues running on next interval even if this execution failed.
-
----
-
-## 🧪 Testing the Example
-
-### Step 1: Enable in Template
-
-```typescript
-// In src/index.ts, add:
-import { 
-  TrackGameScoresTool, 
-  GetGameScoresTool,
-  StopGameTrackingTool 
-} from "./tools/GameScoreTrackerTool";
-
-const gamesSkill = new LuaSkill({
-  name: "games-skill",
-  version: "1.0.0",
-  description: "Live game score tracking",
-  context: "Track live sports scores with automatic updates",
-  tools: [
-    new TrackGameScoresTool(),
-    new GetGameScoresTool(),
-    new StopGameTrackingTool()
-  ]
-});
-```
-
-### Step 2: Compile & Test
-
-```bash
-lua compile
-lua test skill
-
-# Select: track_game_scores
-# Enter:
-# - gameId: LAL-GSW-2025-10-12
-# - gameName: Lakers vs Warriors
-# - startTime: 2025-10-12T19:00:00Z
-# - updateIntervalSeconds: 60
-
-# Output:
-# ✅ Game record created
-# ✅ Score tracking job created: job_abc123
-# 📊 Job will update scores every 60 seconds
-# ⏹️  Job will automatically stop when game ends
-```
-
-### Step 3: Monitor Job
-
-```bash
-# Check job status
-lua jobs production
-# Select: View deployed jobs
-# You'll see: track-game-LAL-GSW-2025-10-12
-
-# Trigger manually to test
-lua jobs production
-# Select: Trigger job now
-# See: Score update happens immediately
-
-# View execution history
-lua jobs production
-# Select: View execution history
-# See: All score updates logged
-```
-
-### Step 4: Get Current Scores
-
-```bash
-lua test skill
-
-# Select: get_game_scores
-# Enter: gameId: LAL-GSW-2025-10-12
-
-# Output:
-# {
-#   "game": {
-#     "name": "Lakers vs Warriors",
-#     "status": "in-progress",
-#     "currentScore": { "home": 45, "away": 42 },
-#     "quarter": 2,
-#     "timeRemaining": "5:23"
-#   }
-# }
-```
-
-### Step 5: Verify Auto-Stop
-
-When the game ends:
-```
-Job executes
-    ↓
-Fetches score: { isFinished: true }
-    ↓
-Logs final score
-    ↓
-Calls Jobs.deactivate(job.jobId)
-    ↓
-Job stops - no more executions! ✅
-```
-
----
-
-## 🎓 What This Example Teaches
-
-### Advanced Patterns
-
-1. **Self-terminating jobs** - Jobs can stop themselves
-2. **Interval with start time** - Delay first execution
-3. **External API integration** - Fetch from external services
-4. **Error recovery** - Continue on errors, stop on success
-5. **Closure serialization** - Complex variable capture
-6. **Mock data fallback** - Demo mode when API unavailable
-
-### Real-World Applications
-
-**Sports Scores:**
-- Track NBA, NFL, soccer games
-- Update scores every minute
-- Stop when game ends
-
-**Auctions:**
-- Monitor auction bids
-- Update every 30 seconds
-- Stop when auction closes
-
-**Stock Monitoring:**
-- Track stock prices
-- Update every 5 minutes during market hours
-- Stop when market closes
-
-**Server Monitoring:**
-- Check server health every 1 minute
-- Stop when maintenance window ends
-
-**Trial Periods:**
-- Check trial status daily
-- Stop when user converts or trial ends
-
----
-
-## 🔧 Customization Examples
-
-### Change Update Frequency
-
-```typescript
-// More frequent updates (every 30 seconds)
-updateIntervalSeconds: 30
-
-// Less frequent (every 5 minutes)
-updateIntervalSeconds: 300
-```
-
-### Add Notifications
-
-```typescript
-execute: async () => {
-  const scoreUpdate = await fetchScores();
-  
-  // Check for significant events
-  if (scoreUpdate.home - scoreUpdate.away >= 10) {
-    // Big lead! Send notification
-    await Data.create('notifications', {
-      type: 'big-lead',
-      gameId: gameId,
-      score: scoreUpdate,
-      timestamp: new Date().toISOString()
-    });
-  }
-  
-  return { scoreUpdate };
-}
-```
-
-### Multiple Stop Conditions
-
-```typescript
-execute: async () => {
-  const gameData = await Data.getEntry('games', gameRecordId);
-  
-  // Stop if game finished
-  if (gameData.data.status === 'finished') {
-    await Jobs.deactivate(job.jobId);
-    return { action: 'stopped', reason: 'game-finished' };
-  }
-  
-  // Stop if timeout (3 hours)
-  const startTime = new Date(gameData.data.startTime);
-  const elapsed = Date.now() - startTime.getTime();
-  const threeHours = 3 * 60 * 60 * 1000;
-  
-  if (elapsed > threeHours) {
-    await Jobs.deactivate(job.jobId);
-    return { action: 'stopped', reason: 'timeout' };
-  }
-  
-  // Continue monitoring
-  return { action: 'continue' };
-}
-```
-
----
-
-## 📊 Job Lifecycle
-
-```
-t=0: Tool creates job
-      |
-      | Schedule: { type: 'interval', seconds: 60 }
-      | Start time: 7:00 PM
-      ↓
-t=7:00 PM: First execution
-      |
-      ↓
-t=7:01 PM: Second execution (60s later)
-      |
-      ↓
-t=7:02 PM: Third execution
-      |
-      | ... continues every 60 seconds ...
-      ↓
-t=9:30 PM: Game ends detected
-      |
-      | Calls: await Jobs.deactivate(job.jobId)
-      ↓
-t=9:30 PM: Job stops ⏹️
-      |
-      | No more executions scheduled
-      ↓
-Done!
-```
-
----
-
-## 🎯 Use Cases Beyond Games
-
-### 1. Auction Monitoring
-
-```typescript
-await Jobs.create({
-  name: `monitor-auction-${auctionId}`,
-  schedule: {
-    type: 'interval',
-    seconds: 30
-  },
-  execute: async () => {
-    const auction = await Data.getEntry('auctions', auctionId);
-    
-    // Check if auction closed
-    if (new Date(auction.data.endTime) < new Date()) {
-      console.log('Auction closed!');
-      await Jobs.deactivate(job.jobId);
-      return { action: 'stopped', winner: auction.data.highestBidder };
-    }
-    
-    // Update current bid
-    const currentBid = await fetchLatestBid(auctionId);
-    await Data.update('auctions', auctionId, { currentBid });
-    
-    return { action: 'updated', currentBid };
-  }
-});
-```
-
-### 2. Server Health Monitoring (with time limit)
-
-```typescript
-await Jobs.create({
-  name: `health-check-deployment-${deploymentId}`,
-  schedule: {
-    type: 'interval',
-    seconds: 10  // Check every 10 seconds
-  },
-  execute: async () => {
-    const deployment = await Data.getEntry('deployments', deploymentId);
-    
-    // Stop if deployment succeeded
-    if (deployment.data.status === 'success') {
-      await Jobs.deactivate(job.jobId);
-      return { action: 'stopped', reason: 'deployment-successful' };
-    }
-    
-    // Stop if timeout (10 minutes)
-    const elapsed = Date.now() - new Date(deployment.data.startTime).getTime();
-    if (elapsed > 10 * 60 * 1000) {
-      await Jobs.deactivate(job.jobId);
-      return { action: 'stopped', reason: 'timeout' };
-    }
-    
-    // Check health
-    const health = await checkServerHealth();
-    await Data.update('deployments', deploymentId, { health });
-    
-    return { action: 'monitoring', health };
-  }
-});
-```
-
-### 3. Limited-Time Promotion
-
-```typescript
-const promotionEnd = new Date('2025-12-25T23:59:59Z');
-
-await Jobs.create({
-  name: `check-promotion-${promoId}`,
-  schedule: {
-    type: 'interval',
-    seconds: 3600  // Check every hour
-  },
-  execute: async () => {
-    // Check if promotion ended
-    if (new Date() > promotionEnd) {
-      console.log('Promotion ended');
-      
-      // Deactivate promotion
-      await Data.update('promotions', promoId, { active: false });
-      
-      // Stop this job
-      await Jobs.deactivate(job.jobId);
-      
-      return { action: 'stopped', reason: 'promotion-ended' };
-    }
-    
-    // Log promotion stats
-    const stats = await getPromotionStats(promoId);
-    await Data.create('promotion-stats', {
-      promoId,
-      stats,
-      timestamp: new Date().toISOString()
-    });
-    
-    return { action: 'logged', stats };
-  }
-});
-```
-
----
-
-## 💡 Advanced Techniques
-
-### Conditional Stop Logic
-
-```typescript
-execute: async () => {
-  const data = await Data.getEntry('collection', recordId);
-  
-  // Multiple stop conditions
-  const stopReasons = [];
-  
-  if (data.data.completed) stopReasons.push('completed');
-  if (data.data.cancelled) stopReasons.push('cancelled');
-  if (data.data.timeout) stopReasons.push('timeout');
-  
-  if (stopReasons.length > 0) {
-    await Jobs.deactivate(job.jobId);
-    return { 
-      action: 'stopped', 
-      reasons: stopReasons 
-    };
-  }
-  
-  // Continue
-  return { action: 'continue' };
-}
-```
-
-### Gradual Slowdown
-
-```typescript
-let executionCount = 0;
-
-execute: async () => {
-  executionCount++;
-  
-  // After 100 executions, slow down the interval
-  if (executionCount >= 100) {
-    // Create a new slower job
-    await Jobs.create({
-      name: `${originalName}-slow`,
-      schedule: { type: 'interval', seconds: 300 }  // 5 min instead of 1 min
-    });
-    
-    // Stop fast job
-    await Jobs.deactivate(job.jobId);
-    
-    return { action: 'switched-to-slow-mode' };
-  }
-  
-  return { action: 'continue', count: executionCount };
-}
-```
-
-### Pause and Resume Based on Time
-
-```typescript
-execute: async () => {
-  const hour = new Date().getHours();
-  
-  // Only run during business hours (9 AM - 5 PM)
-  if (hour < 9 || hour >= 17) {
-    console.log('Outside business hours, skipping');
-    return { action: 'skipped', hour };
-  }
-  
-  // Do work
-  const result = await doWork();
-  
-  return { action: 'processed', result };
-}
-```
-
----
-
-## 🧪 Testing Scenarios
-
-### Test 1: Game In Progress
-
-```bash
-lua test skill
-# Select: track_game_scores
-# Enter:
-#   gameId: TEST-001
-#   gameName: Test Game
-#   startTime: 2025-10-12T20:00:00Z
-#   updateIntervalSeconds: 60
-
-# Result: Job created and will run every 60 seconds
-```
-
-### Test 2: Get Scores
-
-```bash
-lua test skill
-# Select: get_game_scores
-# Enter: gameId: TEST-001
-
-# Result: Current score and game status
-```
-
-### Test 3: Manual Stop
-
-```bash
-lua test skill
-# Select: stop_game_tracking  
-# Enter: gameId: TEST-001
-
-# Result: Job deactivated, game marked as stopped
-```
-
-### Test 4: Trigger Job Manually
-
-```bash
-lua jobs production
-# Select: Trigger job now
-# Select: track-game-TEST-001
-
-# Job executes immediately and logs result
-```
-
----
-
-## 📋 Checklist for Your Own Implementation
-
-When creating similar self-terminating interval jobs:
-
-- [ ] Capture all needed variables before job creation
-- [ ] Use interval schedule with appropriate frequency
-- [ ] Include stop condition check at start of execute
-- [ ] Call `Jobs.deactivate(job.jobId)` when stopping
-- [ ] Log why the job stopped
-- [ ] Store final results before stopping
-- [ ] Handle API errors gracefully (don't stop on errors)
-- [ ] Set appropriate timeout
-- [ ] Configure retry for transient errors
-- [ ] Test manual triggering
-
----
-
-## 🎓 Learn More
-
-### Similar Examples
-- **Stock Price Tracker** - Monitor stocks during market hours, stop at close
-- **Build Monitor** - Check CI/CD status every 10s, stop when complete
-- **Trial Countdown** - Check daily, stop when trial converts/expires
-- **Flash Sale** - Update inventory every 5 seconds, stop when sold out
-
-### Documentation
-- **DYNAMIC_JOB_CREATION_API.md** - Jobs.create() reference
-- **WEBHOOK_JOB_EXAMPLES.md** - More examples
-- **JOB_API_SPEC.md** - Complete API reference
-
----
-
-## ✅ Summary
-
-**This example demonstrates:**
-- ✅ Creating interval jobs dynamically
-- ✅ Jobs that stop themselves
-- ✅ Real-time monitoring patterns
-- ✅ External API integration
-- ✅ Error handling in jobs
-- ✅ Closure capture
-- ✅ Normal TypeScript code (not strings!)
-
-**Perfect for:**
-- Live data monitoring
-- Time-bounded tracking
-- Event-driven scheduling
-- Self-managing background tasks
-
----
-
-**Now you can build sophisticated real-time monitoring systems with clean, self-managing code!** 🎮✨
-