lua-cli 2.5.8 → 3.0.0-alpha.10

package/dist/types/skill.js

@@ -143,3 +143,474 @@ export class LuaSkill {
         return tool.execute(validatedInput);
     }
 }
+/**
+ * Lua Job class.
+ * Main class for building scheduled jobs (cron jobs, one-time tasks, intervals).
+ *
+ * A job is a scheduled task that executes at specific times or intervals.
+ * Jobs can run once, on a recurring schedule (cron), or at fixed intervals.
+ *
+ * @example
+ * ```typescript
+ * import { LuaJob } from 'lua-cli';
+ *
+ * // Daily cleanup job at 2 AM
+ * const dailyCleanup = new LuaJob({
+ *   name: 'daily-cleanup',
+ *   version: '1.0.0',
+ *   description: "Daily database cleanup job",
+ *   context: "Runs at 2 AM daily to clean up old records and optimize tables.",
+ *   schedule: {
+ *     type: 'cron',
+ *     expression: '0 2 * * *',  // 2 AM every day
+ *     timezone: 'America/New_York'
+ *   },
+ *   timeout: 600, // 10 minutes
+ *   retry: {
+ *     maxAttempts: 3,
+ *     backoffSeconds: 60
+ *   },
+ *   execute: async () => {
+ *     // Cleanup logic
+ *     console.log('Running cleanup...');
+ *     return { recordsDeleted: 150 };
+ *   }
+ * });
+ *
+ * // One-time job
+ * const sendWelcome = new LuaJob({
+ *   name: 'send-welcome',
+ *   version: '1.0.0',
+ *   description: "Send welcome email to new users",
+ *   context: "Scheduled one-time task to send welcome emails.",
+ *   schedule: {
+ *     type: 'once',
+ *     executeAt: new Date('2025-12-31T10:00:00Z')
+ *   },
+ *   execute: async () => {
+ *     console.log('Sending welcome emails...');
+ *     return { emailsSent: 100 };
+ *   }
+ * });
+ *
+ * // Interval-based job (every 5 minutes)
+ * const healthCheck = new LuaJob({
+ *   name: 'health-check',
+ *   version: '1.0.0',
+ *   description: "System health check",
+ *   context: "Runs every 5 minutes to check system health.",
+ *   schedule: {
+ *     type: 'interval',
+ *     seconds: 300  // 5 minutes
+ *   },
+ *   execute: async () => {
+ *     return { status: 'healthy' };
+ *   }
+ * });
+ * ```
+ */
+export class LuaJob {
+    /**
+     * Creates a new LuaJob instance.
+     *
+     * @param config - Configuration object containing job metadata
+     * @param config.name - Job name (optional, defaults to 'unnamed-job')
+     * @param config.version - Job version (optional, defaults to '1.0.0')
+     * @param config.description - Short description of what the job does (1-2 sentences)
+     * @param config.context - Detailed explanation of the job's purpose
+     * @param config.schedule - Schedule configuration (cron, once, or interval)
+     * @param config.timeout - Optional timeout in seconds (default: 300)
+     * @param config.retry - Optional retry configuration
+     * @param config.metadata - Optional metadata for the job
+     * @param config.execute - Function that processes the job (receives job instance as parameter)
+     */
+    constructor(config) {
+        this.name = config.name || 'unnamed-job';
+        this.version = config.version || '1.0.0';
+        this.description = config.description;
+        this.context = config.context;
+        this.schedule = config.schedule;
+        this.timeout = config.timeout || 300;
+        this.retry = config.retry;
+        this.metadata = config.metadata;
+        this.executeFunction = config.execute;
+    }
+    /**
+     * Gets the job name.
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Gets the job version.
+     */
+    getVersion() {
+        return this.version;
+    }
+    /**
+     * Gets the job description.
+     */
+    getDescription() {
+        return this.description;
+    }
+    /**
+     * Gets the job context.
+     */
+    getContext() {
+        return this.context;
+    }
+    /**
+     * Gets the job schedule.
+     */
+    getSchedule() {
+        return this.schedule;
+    }
+    /**
+     * Gets the job timeout in seconds.
+     */
+    getTimeout() {
+        return this.timeout;
+    }
+    /**
+     * Gets the retry configuration.
+     */
+    getRetry() {
+        return this.retry;
+    }
+    /**
+     * Gets the job metadata.
+     */
+    getMetadata() {
+        return this.metadata;
+    }
+}
+/**
+ * Lua Webhook class.
+ * Main class for building webhooks with validated inputs.
+ *
+ * A webhook is an HTTP endpoint that can receive requests with validated
+ * query parameters, headers, and body. The execute function processes the
+ * validated input and returns a response.
+ *
+ * @example
+ * ```typescript
+ * import { LuaWebhook } from 'lua-cli';
+ * import { z } from 'zod';
+ *
+ * const webhook = new LuaWebhook({
+ *   name: 'user-created',
+ *   version: '1.0.0',
+ *   description: "Webhook that handles user creation events",
+ *   context: "This webhook processes new user registration events. " +
+ *            "It validates the user data and sends welcome emails.",
+ *   querySchema: z.object({
+ *     source: z.string().optional()
+ *   }),
+ *   headerSchema: z.object({
+ *     'x-api-key': z.string(),
+ *     'content-type': z.string().optional()
+ *   }),
+ *   bodySchema: z.object({
+ *     userId: z.string(),
+ *     email: z.string().email(),
+ *     name: z.string()
+ *   }),
+ *   execute: async (query, headers, body) => {
+ *     // Process the webhook...
+ *     console.log('New user:', body.email);
+ *     return { success: true, userId: body.userId };
+ *   }
+ * });
+ *
+ * // Execute the webhook with validated inputs
+ * const result = await webhook.execute(
+ *   { source: 'mobile' },
+ *   { 'x-api-key': 'secret-key' },
+ *   { userId: '123', email: 'user@example.com', name: 'John' }
+ * );
+ * ```
+ */
+export class LuaWebhook {
+    /**
+     * Creates a new LuaWebhook instance.
+     *
+     * @param config - Configuration object containing webhook metadata
+     * @param config.name - Webhook name (optional, defaults to 'unnamed-webhook')
+     * @param config.version - Webhook version (optional, defaults to '1.0.0')
+     * @param config.description - Short description of what the webhook does (1-2 sentences)
+     * @param config.context - Detailed explanation of the webhook's purpose and behavior
+     * @param config.querySchema - Optional Zod schema for query parameter validation
+     * @param config.headerSchema - Optional Zod schema for header validation
+     * @param config.bodySchema - Optional Zod schema for body validation
+     * @param config.execute - Function that processes the webhook request
+     */
+    constructor(config) {
+        this.name = config.name || 'unnamed-webhook';
+        this.version = config.version || '1.0.0';
+        this.description = config.description;
+        this.context = config.context;
+        this.querySchema = config.querySchema;
+        this.headerSchema = config.headerSchema;
+        this.bodySchema = config.bodySchema;
+        this.executeFunction = config.execute;
+    }
+    /**
+     * Gets the webhook name.
+     */
+    getName() {
+        return this.name;
+    }
+    /**
+     * Gets the webhook version.
+     */
+    getVersion() {
+        return this.version;
+    }
+    /**
+     * Gets the webhook description.
+     */
+    getDescription() {
+        return this.description;
+    }
+    /**
+     * Gets the webhook context.
+     */
+    getContext() {
+        return this.context;
+    }
+    /**
+     * Executes the webhook with validated input.
+     * Validates query parameters, headers, and body against their respective schemas
+     * before executing the webhook function.
+     *
+     * @param query - Query parameters object
+     * @param headers - Headers object
+     * @param body - Request body
+     * @returns Promise resolving to webhook execution result
+     * @throws Error if validation fails for any input
+     *
+     * @example
+     * ```typescript
+     * const result = await webhook.execute(
+     *   { limit: '10' },
+     *   { 'x-api-key': 'secret' },
+     *   { data: 'value' }
+     * );
+     * ```
+     */
+    async execute(query, headers, body) {
+        let validatedQuery = query;
+        let validatedHeaders = headers;
+        let validatedBody = body;
+        // Validate query parameters if schema is provided
+        if (this.querySchema) {
+            try {
+                validatedQuery = this.querySchema.parse(query || {});
+            }
+            catch (error) {
+                throw new Error(`Query parameter validation failed: ${error}`);
+            }
+        }
+        // Validate headers if schema is provided
+        if (this.headerSchema) {
+            try {
+                validatedHeaders = this.headerSchema.parse(headers || {});
+            }
+            catch (error) {
+                throw new Error(`Header validation failed: ${error}`);
+            }
+        }
+        // Validate body if schema is provided
+        if (this.bodySchema) {
+            try {
+                validatedBody = this.bodySchema.parse(body);
+            }
+            catch (error) {
+                throw new Error(`Body validation failed: ${error}`);
+            }
+        }
+        // Execute the webhook function with validated inputs as separate parameters
+        return this.executeFunction(validatedQuery, validatedHeaders, validatedBody);
+    }
+}
+/**
+ * PreProcessor class.
+ * Processes user messages before they reach the agent.
+ * Can handle rich content (text, images, files).
+ *
+ * @example
+ * ```typescript
+ * const contentFilter = new PreProcessor({
+ *   name: 'content-filter',
+ *   version: '1.0.0',
+ *   description: 'Filters and processes message content',
+ *   context: 'Filters spam, validates images, and adds context',
+ *   execute: async (user, messages, channel) => {
+ *     // Process each message
+ *     return messages.map(msg => {
+ *       if (msg.type === 'text') {
+ *         // Filter spam from text
+ *         const filtered = msg.text.replace(/spam/gi, '[filtered]');
+ *         return { type: 'text', text: filtered };
+ *       }
+ *       if (msg.type === 'image') {
+ *         // Could validate image, add watermark, etc.
+ *         return msg;
+ *       }
+ *       return msg;
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export class PreProcessor {
+    constructor(config) {
+        this.name = config.name || 'unnamed-preprocessor';
+        this.version = config.version || '1.0.0';
+        this.description = config.description;
+        this.context = config.context;
+        this.asyncMode = config.async ?? false; // Default to synchronous
+        this.executeFunction = config.execute;
+    }
+    getName() {
+        return this.name;
+    }
+    getVersion() {
+        return this.version;
+    }
+    getDescription() {
+        return this.description;
+    }
+    getContext() {
+        return this.context;
+    }
+    getAsync() {
+        return this.asyncMode;
+    }
+    async execute(user, messages, channel) {
+        return this.executeFunction(user, messages, channel);
+    }
+}
+/**
+ * PostProcessor class.
+ * Processes agent responses before they reach the user.
+ *
+ * @example
+ * ```typescript
+ * const responseFormatter = new PostProcessor({
+ *   name: 'response-formatter',
+ *   version: '1.0.0',
+ *   description: 'Formats responses with branding',
+ *   context: 'Adds company signature to all responses',
+ *   execute: async (user, message, response, channel) => {
+ *     return response + '\n\n---\nPowered by Acme Corp';
+ *   }
+ * });
+ * ```
+ */
+export class PostProcessor {
+    constructor(config) {
+        this.name = config.name || 'unnamed-postprocessor';
+        this.version = config.version || '1.0.0';
+        this.description = config.description;
+        this.context = config.context;
+        this.asyncMode = config.async ?? false; // Default to synchronous
+        this.executeFunction = config.execute;
+    }
+    getName() {
+        return this.name;
+    }
+    getVersion() {
+        return this.version;
+    }
+    getDescription() {
+        return this.description;
+    }
+    getContext() {
+        return this.context;
+    }
+    getAsync() {
+        return this.asyncMode;
+    }
+    async execute(user, message, response, channel) {
+        return this.executeFunction(user, message, response, channel);
+    }
+}
+/**
+ * LuaAgent class.
+ * Unified agent configuration that consolidates skills, webhooks, jobs, and processors.
+ *
+ * This is the simplest way to define an agent. Instead of exporting multiple separate
+ * components, you create one LuaAgent that contains everything.
+ *
+ * @example
+ * ```typescript
+ * import { LuaAgent, LuaSkill, LuaJob, LuaWebhook } from 'lua-cli';
+ *
+ * // Define your skills, jobs, webhooks in separate files
+ * import { userSkill } from './skills/user-skill';
+ * import { healthCheckJob } from './jobs/health-check';
+ * import { webhookHandler } from './webhooks/handler';
+ *
+ * // Create a single agent configuration
+ * export const agent = new LuaAgent({
+ *   name: 'my-assistant',
+ *   persona: 'You are a helpful AI assistant that can manage users and products.',
+ *   welcomeMessage: 'Hello! How can I help you today?',
+ *   skills: [userSkill],
+ *   jobs: [healthCheckJob],
+ *   webhooks: [webhookHandler],
+ *   preProcessors: [],
+ *   postProcessors: []
+ * });
+ * ```
+ */
+export class LuaAgent {
+    /**
+     * Creates a new LuaAgent instance.
+     *
+     * @param config - Agent configuration
+     * @param config.name - Agent name
+     * @param config.persona - Agent persona (behavior and personality)
+     * @param config.welcomeMessage - Optional welcome message
+     * @param config.skills - Optional array of skills
+     * @param config.webhooks - Optional array of webhooks
+     * @param config.jobs - Optional array of jobs
+     * @param config.preProcessors - Optional array of preprocessors
+     * @param config.postProcessors - Optional array of postprocessors
+     */
+    constructor(config) {
+        this.name = config.name;
+        this.persona = config.persona;
+        this.welcomeMessage = config.welcomeMessage;
+        this.skills = config.skills || [];
+        this.webhooks = config.webhooks || [];
+        this.jobs = config.jobs || [];
+        this.preProcessors = config.preProcessors || [];
+        this.postProcessors = config.postProcessors || [];
+    }
+    getName() {
+        return this.name;
+    }
+    getPersona() {
+        return this.persona;
+    }
+    getWelcomeMessage() {
+        return this.welcomeMessage;
+    }
+    getSkills() {
+        return this.skills;
+    }
+    getWebhooks() {
+        return this.webhooks;
+    }
+    getJobs() {
+        return this.jobs;
+    }
+    getPreProcessors() {
+        return this.preProcessors;
+    }
+    getPostProcessors() {
+        return this.postProcessors;
+    }
+}

package/dist/utils/agent-management.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent Management Utilities
+ * Handles LuaAgent persona and welcome message synchronization with lua.skill.yaml
+ */
+/**
+ * Syncs the agent's persona and welcome message with lua.skill.yaml.
+ * This ensures the YAML configuration reflects the agent definition in code.
+ *
+ * @param agentMetadata - Agent metadata extracted from LuaAgent
+ */
+export declare function syncAgentPersonaWithYaml(agentMetadata: {
+    name: string;
+    persona: string;
+    welcomeMessage?: string;
+}): Promise<void>;
+/**
+ * Reads the agent persona from lua.skill.yaml.
+ * This can be used to ensure the code and YAML are in sync.
+ *
+ * @returns Agent persona and welcome message from YAML, or null if not found
+ */
+export declare function readAgentPersonaFromYaml(): {
+    persona?: string;
+    welcomeMessage?: string;
+} | null;

package/dist/utils/agent-management.js

@@ -0,0 +1,67 @@
+/**
+ * Agent Management Utilities
+ * Handles LuaAgent persona and welcome message synchronization with lua.skill.yaml
+ */
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import { COMPILE_FILES, YAML_FORMAT } from '../config/compile.constants.js';
+/**
+ * Syncs the agent's persona and welcome message with lua.skill.yaml.
+ * This ensures the YAML configuration reflects the agent definition in code.
+ *
+ * @param agentMetadata - Agent metadata extracted from LuaAgent
+ */
+export async function syncAgentPersonaWithYaml(agentMetadata) {
+    const yamlPath = path.join(process.cwd(), COMPILE_FILES.LUA_SKILL_YAML);
+    // Read existing YAML config
+    let config = {};
+    if (fs.existsSync(yamlPath)) {
+        const yamlContent = fs.readFileSync(yamlPath, 'utf8');
+        config = yaml.load(yamlContent);
+    }
+    // Update agent section with persona and welcome message
+    config.agent = {
+        ...config.agent,
+        persona: agentMetadata.persona,
+        welcomeMessage: agentMetadata.welcomeMessage
+    };
+    // Write updated YAML with consistent formatting
+    const yamlContent = yaml.dump(config, {
+        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);
+    console.log(`✅ Synced agent persona to lua.skill.yaml`);
+}
+/**
+ * Reads the agent persona from lua.skill.yaml.
+ * This can be used to ensure the code and YAML are in sync.
+ *
+ * @returns Agent persona and welcome message from YAML, or null if not found
+ */
+export function readAgentPersonaFromYaml() {
+    const yamlPath = path.join(process.cwd(), COMPILE_FILES.LUA_SKILL_YAML);
+    if (!fs.existsSync(yamlPath)) {
+        return null;
+    }
+    try {
+        const yamlContent = fs.readFileSync(yamlPath, 'utf8');
+        const config = yaml.load(yamlContent);
+        if (config.agent) {
+            return {
+                persona: config.agent.persona,
+                welcomeMessage: config.agent.welcomeMessage
+            };
+        }
+    }
+    catch (error) {
+        console.warn(`Warning: Could not read agent persona from lua.skill.yaml: ${error}`);
+    }
+    return null;
+}

package/dist/utils/bundling.d.ts

@@ -2,8 +2,15 @@
  * Bundling Utilities
  * Handles esbuild bundling of tools and main index
  */
-import { ToolInfo } from '../interfaces/compile.js';
+import { Plugin } from "esbuild";
 import { Project } from "ts-morph";
+import { ToolInfo } from '../interfaces/compile.js';
+/**
+ * esbuild plugin to inject sandbox globals instead of requiring lua-cli
+ * This removes require("lua-cli") statements and injects the global API objects
+ * that are available in the sandbox (Products, User, Data, Baskets, Orders, Webhooks, Jobs)
+ */
+export declare const sandboxGlobalsPlugin: Plugin;
 /**
  * Bundles a tool's TypeScript code into a standalone JavaScript file.
  * Uses esbuild to:
@@ -11,10 +18,12 @@ import { Project } from "ts-morph";
  * - Minify code for production
  * - Wrap for VM execution
  *
+ * For inline tools (defined in index.ts), creates a temporary export file first.
+ *
  * @param tool - The tool to bundle
  * @param distDir - The distribution directory for output
  */
-export declare function bundleTool(tool: ToolInfo, distDir: string): Promise<void>;
+export declare function bundleTool(tool: ToolInfo, distDir: string, modifiedSource?: string): Promise<void>;
 /**
  * Bundles the main index.ts file into a standalone JavaScript file.
  * This creates the entry point for the skill.
@@ -23,14 +32,44 @@ export declare function bundleTool(tool: ToolInfo, distDir: string): Promise<voi
  * @param distDir - The distribution directory for output
  */
 export declare function bundleMainIndex(indexPath: string, distDir: string): Promise<void>;
+/**
+ * Extracts and bundles webhook execute function and schemas.
+ *
+ * @param webhook - Webhook metadata with name and version
+ * @param indexFile - The TypeScript source file containing the webhook
+ * @param distDir - Distribution directory for output
+ * @param project - Optional ts-morph Project for resolving imports
+ * @returns Webhook with bundled code and schemas
+ */
+export declare function bundleWebhook(webhook: any, indexFile: any, distDir: string, project?: any): Promise<any>;
+/**
+ * Extracts and bundles job execute function.
+ *
+ * @param job - Job metadata with name and version
+ * @param indexFile - The TypeScript source file containing the job
+ * @param distDir - Distribution directory for output
+ * @param project - Optional ts-morph Project for resolving imports
+ * @returns Job with bundled code
+ */
+export declare function bundleJob(job: any, indexFile: any, distDir: string, project?: any): Promise<any>;
+/**
+ * Bundles and compresses preprocessor execute function code.
+ */
+export declare function bundlePreProcessor(preprocessor: any, indexFile: any, distDir: string, project?: any): Promise<any>;
+/**
+ * Bundles and compresses postprocessor execute function code.
+ */
+export declare function bundlePostProcessor(postprocessor: any, indexFile: any, distDir: string, project?: any): Promise<any>;
 /**
  * Extracts execute code and input schema from a tool.
  * This function:
  * 1. Reads the bundled tool code
- * 2. Extracts the execute function
- * 3. Converts Zod schema to JSON Schema format
+ * 2. Detects and bundles any Jobs.create() calls within execute
+ * 3. Extracts the execute function
+ * 4. Converts Zod schema to JSON Schema format
  *
  * @param tool - The tool to extract metadata from (mutated with executeCode and inputSchema)
  * @param project - The ts-morph Project instance for AST analysis
+ * @param distDir - Distribution directory for bundling nested jobs
  */
-export declare function extractExecuteCode(tool: ToolInfo, project: Project): Promise<void>;
+export declare function extractExecuteCode(tool: ToolInfo, project: Project, distDir?: string): Promise<void>;