lua-cli 2.5.8 → 3.0.0-alpha.1

package/dist/utils/webhook-management.js

@@ -0,0 +1,256 @@
+/**
+ * Webhook Management Utilities
+ * Handles webhook creation via API and YAML configuration management
+ */
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import WebhookApi from '../api/webhook.api.service.js';
+import { BASE_URLS } from '../config/constants.js';
+import { loadApiKey } from '../services/auth.js';
+import { COMPILE_FILES, SKILL_DEFAULTS, YAML_FORMAT, } from '../config/compile.constants.js';
+/**
+ * Ensures all detected webhooks exist in the YAML config with valid webhook IDs.
+ * If a webhook doesn't exist or has no ID, creates it via the API.
+ *
+ * @param webhooksArray - Array of webhooks detected from source code
+ * @param config - The skill configuration from lua.skill.yaml
+ * @returns Updated webhooks array with valid webhook IDs
+ */
+export async function ensureWebhooksExistInYaml(webhooksArray, config) {
+    const updatedWebhooksArray = [];
+    let yamlUpdated = false;
+    const existingWebhooks = config?.webhooks || [];
+    const existingWebhooksMap = createWebhooksMap(existingWebhooks);
+    // Process each detected webhook
+    for (const webhook of webhooksArray) {
+        const existingWebhook = existingWebhooksMap.get(webhook.name);
+        if (existingWebhook && existingWebhook.webhookId && existingWebhook.webhookId !== '') {
+            // Webhook exists with valid webhookId - reuse it
+            updatedWebhooksArray.push({
+                ...webhook,
+                webhookId: existingWebhook.webhookId
+            });
+        }
+        else {
+            // Webhook doesn't exist or missing webhookId - create via API
+            const createdWebhook = await createWebhookViaApi(webhook, config, existingWebhooks, existingWebhook);
+            updatedWebhooksArray.push(createdWebhook);
+            yamlUpdated = true;
+        }
+    }
+    // Update YAML file if any changes were made
+    if (yamlUpdated) {
+        await updateYamlWithWebhooks(config);
+    }
+    return updatedWebhooksArray;
+}
+/**
+ * Creates a map of existing webhooks for quick lookup by name.
+ *
+ * @param existingWebhooks - Array of webhooks from YAML config
+ * @returns Map of webhook names to webhook objects
+ */
+function createWebhooksMap(existingWebhooks) {
+    const map = new Map();
+    existingWebhooks.forEach((webhook) => {
+        map.set(webhook.name, webhook);
+    });
+    return map;
+}
+/**
+ * Creates a new webhook via the Lua API and updates the config.
+ *
+ * @param webhook - The webhook to create
+ * @param config - The skill configuration
+ * @param existingWebhooks - Array of existing webhooks (mutated)
+ * @param existingWebhook - The existing webhook entry if one exists (may be without ID)
+ * @returns The webhook with its new ID
+ */
+async function createWebhookViaApi(webhook, config, existingWebhooks, existingWebhook) {
+    try {
+        // Validate prerequisites
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            throw new Error("No API key found. Run 'lua auth configure' first.");
+        }
+        const agentId = config?.agent?.agentId;
+        if (!agentId) {
+            throw new Error("No agent ID found in lua.skill.yaml. Run 'lua init' first.");
+        }
+        // Create webhook via API
+        const webhookPayload = {
+            name: webhook.name,
+            description: webhook.description || `A Lua webhook for ${webhook.name}`,
+            context: webhook.context || ''
+        };
+        const webhookApi = new WebhookApi(BASE_URLS.API, apiKey, agentId);
+        const result = await webhookApi.createWebhook(webhookPayload);
+        if (result.success && result.data && result.data.id) {
+            const newWebhookId = result.data.id;
+            // Update YAML config with new webhook ID
+            if (!existingWebhook) {
+                existingWebhooks.push({
+                    name: webhook.name || '',
+                    version: webhook.version || SKILL_DEFAULTS.VERSION,
+                    webhookId: newWebhookId
+                });
+            }
+            else {
+                existingWebhook.webhookId = newWebhookId;
+            }
+            // Add webhooks to config if not already present
+            if (!config.webhooks) {
+                config.webhooks = existingWebhooks;
+            }
+            return {
+                ...webhook,
+                webhookId: newWebhookId
+            };
+        }
+        else {
+            console.error(`❌ Failed to create webhook ${webhook.name}:`, result.error);
+            throw new Error(result.error?.message || 'Failed to create webhook - no ID returned from API');
+        }
+    }
+    catch (error) {
+        console.error(`❌ Failed to create webhook ${webhook.name}:`, error);
+        throw error;
+    }
+}
+/**
+ * Updates the lua.skill.yaml file with the current webhooks array.
+ * Ensures no undefined values are written to the YAML file.
+ *
+ * @param config - Current skill configuration to merge with
+ */
+async function updateYamlWithWebhooks(config) {
+    const webhooks = config?.webhooks || [];
+    // Clean webhooks array to ensure no undefined values
+    const cleanedWebhooks = webhooks.map(webhook => ({
+        name: webhook.name || '',
+        version: webhook.version || SKILL_DEFAULTS.VERSION,
+        webhookId: webhook.webhookId || ''
+    }));
+    // Update config with cleaned webhooks array
+    const updatedConfig = {
+        ...config,
+        webhooks: cleanedWebhooks
+    };
+    // Write updated YAML with consistent formatting
+    const yamlPath = path.join(process.cwd(), COMPILE_FILES.LUA_SKILL_YAML);
+    const yamlContent = yaml.dump(updatedConfig, {
+        indent: YAML_FORMAT.INDENT,
+        lineWidth: YAML_FORMAT.LINE_WIDTH,
+        noRefs: YAML_FORMAT.NO_REFS,
+        replacer: (key, value) => {
+            // Replace undefined values with empty strings
+            return value === undefined ? '' : value;
+        }
+    });
+    fs.writeFileSync(yamlPath, yamlContent);
+}
+/**
+ * Syncs the server webhooks with the YAML configuration.
+ * Performs a two-way sync:
+ * 1. Deletes/deactivates webhooks from server that aren't in YAML
+ * 2. Updates YAML with active version numbers from server
+ *
+ * @param config - The skill configuration from lua.skill.yaml
+ * @returns Array of messages about sync operations
+ */
+export async function syncServerWebhooksWithYaml(config) {
+    const messages = [];
+    let yamlNeedsUpdate = false;
+    try {
+        // Validate prerequisites
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            console.warn("⚠️  No API key found. Skipping server webhook sync.");
+            return messages;
+        }
+        const agentId = config?.agent?.agentId;
+        if (!agentId) {
+            console.warn("⚠️  No agent ID found in lua.skill.yaml. Skipping server webhook sync.");
+            return messages;
+        }
+        // Get webhooks from server
+        const webhookApi = new WebhookApi(BASE_URLS.API, apiKey, agentId);
+        const serverWebhooksResponse = await webhookApi.getWebhooks();
+        if (!serverWebhooksResponse.success || !serverWebhooksResponse.data?.webhooks) {
+            console.warn("⚠️  Could not retrieve server webhooks. Skipping server webhook sync.");
+            return messages;
+        }
+        const serverWebhooks = serverWebhooksResponse.data.webhooks;
+        const yamlWebhooks = config?.webhooks || [];
+        // Create maps for efficient lookup
+        const yamlWebhooksMap = new Map(yamlWebhooks
+            .filter((webhook) => webhook.webhookId)
+            .map((webhook) => [webhook.webhookId, webhook]));
+        const serverWebhooksMap = new Map(serverWebhooks.map(webhook => [webhook.id, webhook]));
+        // Part 1: Delete webhooks from server that aren't in YAML
+        const webhooksToDelete = serverWebhooks.filter(serverWebhook => !yamlWebhooksMap.has(serverWebhook.id));
+        for (const webhook of webhooksToDelete) {
+            try {
+                const deleteResponse = await webhookApi.deleteWebhook(webhook.id);
+                if (deleteResponse.success && deleteResponse.data) {
+                    if (deleteResponse.data.deleted) {
+                        const msg = `✅ Deleted webhook "${webhook.name}" from server`;
+                        messages.push(msg);
+                        console.log(msg);
+                    }
+                    else if (deleteResponse.data.deactivated) {
+                        const msg = `⚠️  Webhook "${webhook.name}" has versions and cannot be deleted. It has been deactivated instead.`;
+                        messages.push(msg);
+                        console.warn(msg);
+                    }
+                }
+                else {
+                    const msg = `❌ Failed to delete webhook "${webhook.name}": ${deleteResponse.error?.message || 'Unknown error'}`;
+                    messages.push(msg);
+                    console.error(msg);
+                }
+            }
+            catch (error) {
+                const msg = `❌ Error deleting webhook "${webhook.name}": ${error}`;
+                messages.push(msg);
+                console.error(msg);
+            }
+        }
+        // Part 2: Sync version numbers from server to YAML
+        const updatedYamlWebhooks = yamlWebhooks.map((yamlWebhook) => {
+            const serverWebhook = serverWebhooksMap.get(yamlWebhook.webhookId);
+            if (serverWebhook && serverWebhook.versions && serverWebhook.versions.length > 0) {
+                // Find the active version on the server
+                const activeVersion = serverWebhook.versions.find((v) => v.isActive);
+                if (activeVersion && activeVersion.version !== yamlWebhook.version) {
+                    const msg = `📝 Updated "${yamlWebhook.name}" webhook version in YAML: ${yamlWebhook.version} → ${activeVersion.version}`;
+                    messages.push(msg);
+                    console.log(msg);
+                    yamlNeedsUpdate = true;
+                    return {
+                        ...yamlWebhook,
+                        version: activeVersion.version
+                    };
+                }
+            }
+            return yamlWebhook;
+        });
+        // Update YAML file if versions changed
+        if (yamlNeedsUpdate) {
+            const updatedConfig = {
+                ...config,
+                webhooks: updatedYamlWebhooks
+            };
+            await updateYamlWithWebhooks(updatedConfig);
+            console.log("✅ YAML webhook versions synced with server");
+        }
+        if (webhooksToDelete.length === 0 && !yamlNeedsUpdate) {
+            console.log("✅ Server webhooks and YAML are fully in sync");
+        }
+    }
+    catch (error) {
+        console.error("❌ Error syncing server webhooks:", error);
+    }
+    return messages;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "2.5.8",
+  "version": "3.0.0-alpha.1",
   "description": "Command-line interface for Lua AI platform - develop, test, and deploy LuaSkills with custom tools",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",

package/template/AGENT_CONFIGURATION.md

@@ -0,0 +1,251 @@
+# Agent Configuration Guide
+
+## Overview
+
+There are two ways to configure your Lua agent:
+
+1. **LuaAgent (Recommended)** - Unified, simple approach
+2. **Individual Components (Legacy)** - Separate exports for each component
+
+Both approaches are fully supported and backward compatible.
+
+## Approach 1: LuaAgent (Recommended)
+
+The `LuaAgent` provides a simplified, unified way to configure your agent. All components (skills, webhooks, jobs, processors) are defined in one place.
+
+### Benefits
+
+- **Simpler**: One object contains everything
+- **Clearer**: Easy to see all components at a glance
+- **Persona Sync**: Agent persona automatically syncs with `lua.skill.yaml`
+- **Better Organization**: Natural hierarchy of components
+- **Less Boilerplate**: No need to export multiple separate items
+
+### Example
+
+```typescript
+import { LuaAgent, LuaSkill } from 'lua-cli';
+import { weatherSkill } from './skills/weather';
+import { userSkill } from './skills/user';
+import { healthCheckJob } from './jobs/health-check';
+import { userWebhook } from './webhooks/user';
+
+// Define your agent with all components in one place
+export const agent = new LuaAgent({
+  name: 'my-assistant',
+  
+  // Agent personality and behavior
+  persona: `You are a helpful assistant that can provide weather information
+            and manage user accounts. Be friendly and concise.`,
+  
+  // Welcome message shown to new users
+  welcomeMessage: 'Hello! How can I help you today?',
+  
+  // Skills - collections of tools
+  skills: [weatherSkill, userSkill],
+  
+  // Webhooks - HTTP endpoints for external events
+  webhooks: [userWebhook],
+  
+  // Jobs - scheduled tasks
+  jobs: [healthCheckJob],
+  
+  // Preprocessors - modify messages before they reach the agent
+  preProcessors: [],
+  
+  // Postprocessors - modify responses before they reach the user
+  postProcessors: []
+});
+```
+
+### File Structure
+
+When using `LuaAgent`, organize your code like this:
+
+```
+src/
+├── index.ts                    # Main agent configuration
+├── skills/
+│   ├── weather-skill.ts       # Weather skill with tools
+│   └── user-skill.ts          # User management skill
+├── tools/
+│   ├── WeatherTool.ts         # Individual tool classes
+│   └── UserTool.ts
+├── webhooks/
+│   └── UserWebhook.ts         # Webhook handlers
+├── jobs/
+│   └── HealthCheckJob.ts      # Scheduled jobs
+└── processors/
+    ├── MessageFilter.ts       # Preprocessors
+    └── ResponseFormatter.ts   # Postprocessors
+```
+
+### Compilation
+
+When you run `lua compile`, the compiler will:
+
+1. Detect the `LuaAgent` in `index.ts`
+2. Extract the agent's persona and welcome message
+3. Sync them with `lua.skill.yaml`
+4. Extract all skills, webhooks, jobs, and processors
+5. Bundle and deploy everything
+
+Output during compilation:
+```
+✨ Found LuaAgent: my-assistant
+   Using new unified agent configuration approach
+✅ Synced agent persona to lua.skill.yaml
+📦 Agent contains: 2 skill(s), 1 webhook(s), 1 job(s), 0 preprocessor(s), 0 postprocessor(s)
+```
+
+## Approach 2: Individual Components (Legacy)
+
+The legacy approach exports each component type separately. This is still fully supported for backward compatibility.
+
+### Example
+
+```typescript
+import { LuaSkill, LuaJob, LuaWebhook } from 'lua-cli';
+
+// Export skills individually
+export const weatherSkill = new LuaSkill({
+  name: 'weather-skill',
+  version: '1.0.0',
+  description: 'Weather information',
+  context: 'Provides current weather data',
+  tools: [new GetWeatherTool()]
+});
+
+export const userSkill = new LuaSkill({
+  name: 'user-skill',
+  version: '1.0.0',
+  description: 'User management',
+  context: 'Manages user accounts',
+  tools: [new GetUserTool()]
+});
+
+// Export jobs individually
+export const healthCheckJob = new LuaJob({
+  name: 'health-check',
+  version: '1.0.0',
+  description: 'System health check',
+  context: 'Monitors system status',
+  schedule: { type: 'interval', seconds: 300 },
+  execute: async () => {
+    return { status: 'healthy' };
+  }
+});
+
+// Export webhooks individually
+export const userWebhook = new LuaWebhook({
+  name: 'user-webhook',
+  version: '1.0.0',
+  description: 'User event handler',
+  context: 'Processes user events',
+  execute: async ({ body }) => {
+    return { received: true };
+  }
+});
+```
+
+### Compilation
+
+When you run `lua compile`, the compiler will:
+
+1. Scan for individual `LuaSkill`, `LuaJob`, `LuaWebhook`, etc.
+2. Extract each component separately
+3. Bundle and deploy everything
+
+Output during compilation:
+```
+ℹ️  No LuaAgent found, using legacy detection for individual components
+📦 Found 2 skill(s)...
+📦 Found 1 webhook(s)...
+📦 Found 1 job(s)...
+```
+
+## Comparison
+
+| Feature | LuaAgent | Individual Components |
+|---------|----------|----------------------|
+| **Configuration Style** | Single unified object | Multiple separate exports |
+| **Persona Management** | Auto-synced with YAML | Manual YAML editing |
+| **Code Organization** | Hierarchical | Flat |
+| **Ease of Use** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
+| **Backward Compatible** | ✅ | ✅ |
+| **Use Case** | New projects, simple setup | Existing projects, gradual migration |
+
+## When to Use Each Approach
+
+### Use LuaAgent when:
+
+- ✅ Starting a new project
+- ✅ You want a simple, unified configuration
+- ✅ You want automatic persona synchronization
+- ✅ You prefer a clear hierarchy of components
+
+### Use Individual Components when:
+
+- ✅ Maintaining an existing project
+- ✅ Gradually migrating to the new approach
+- ✅ You prefer more granular control
+- ✅ Working with a legacy codebase
+
+## Migration Guide
+
+If you have an existing project using individual components, you can migrate to `LuaAgent` gradually:
+
+### Step 1: Keep Your Existing Files
+
+Don't change your skill/webhook/job definitions. They can stay in separate files.
+
+### Step 2: Create LuaAgent
+
+In your `index.ts`, import all components and create a `LuaAgent`:
+
+```typescript
+// Import existing components
+import { weatherSkill } from './skills/weather';
+import { userSkill } from './skills/user';
+import { healthCheckJob } from './jobs/health-check';
+
+// Create LuaAgent that references them
+export const agent = new LuaAgent({
+  name: 'my-assistant',
+  persona: 'Your agent persona here',
+  skills: [weatherSkill, userSkill],
+  jobs: [healthCheckJob]
+});
+```
+
+### Step 3: Remove Individual Exports
+
+Remove any `export` keywords from your skill/webhook/job files, or keep them for testing.
+
+### Step 4: Test
+
+Run `lua compile` to verify everything works:
+
+```bash
+lua compile
+```
+
+You should see:
+```
+✨ Found LuaAgent: my-assistant
+```
+
+## Examples
+
+See the following files for complete examples:
+
+- `src/index-agent-example.ts` - LuaAgent approach (recommended)
+- `src/index.ts` - Individual components approach (legacy)
+
+## Questions?
+
+- Check the main README.md for more information
+- See QUICKSTART.md for getting started
+- View WEBHOOK_JOB_EXAMPLES.md for webhook and job examples
+- Read COMPLEX_JOB_EXAMPLES.md for advanced job patterns
+