lua-cli 2.2.8-alpha.1 → 2.3.0-alpha.1

package/dist/{skill.js → types/skill.js}

@@ -1,12 +1,18 @@
-import { assertValidToolName } from "./types/index.js";
+/**
+ * Lua Skill System
+ * Core types and classes for building Lua AI skills
+ */
+import { assertValidToolName } from "./tool-validation.js";
 import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
-import dotenv from "dotenv";
-dotenv.config();
 /**
- * Safe environment variable access function
- * Gets injected at runtime with skill-specific environment variables
+ * Safe environment variable access function.
+ * Gets injected at runtime with skill-specific environment variables.
+ *
+ * Checks in order:
+ * 1. Process environment variables (.env file)
+ * 2. lua.skill.yaml configuration
  *
  * @param key - The environment variable key to retrieve
  * @returns The environment variable value or undefined if not found
@@ -20,13 +26,13 @@ dotenv.config();
 export const env = (key) => {
     // Try to load environment variables from lua.skill.yaml
     try {
+        // Check process.env first (.env file)
+        if (process.env[key]) {
+            return process.env[key];
+        }
         // Look for lua.skill.yaml in current directory and parent directories
         let currentDir = process.cwd();
         let yamlPath = null;
-        //check if in .env file
-        if (dotenv.config().parsed?.[key]) {
-            return dotenv.config().parsed?.[key];
-        }
         while (currentDir !== path.dirname(currentDir)) {
             const potentialPath = path.join(currentDir, 'lua.skill.yaml');
             if (fs.existsSync(potentialPath)) {
@@ -47,21 +53,40 @@ export const env = (key) => {
     }
     return undefined;
 };
+/**
+ * Lua Skill class.
+ * Main class for building AI skills with tools.
+ *
+ * A skill is a collection of tools that the AI agent can use to accomplish tasks.
+ * Tools are functions with validated inputs and well-defined outputs.
+ *
+ * @example
+ * ```typescript
+ * import { LuaSkill } from 'lua-cli';
+ *
+ * const skill = new LuaSkill({
+ *   name: 'weather-skill',
+ *   version: '1.0.0',
+ *   description: "Weather and calculator utilities",
+ *   context: "This skill provides weather information and math operations. " +
+ *            "Use get_weather for current conditions and calculator for arithmetic.",
+ *   tools: [weatherTool, calculatorTool]
+ * });
+ *
+ * // Or add tools after construction
+ * skill.addTool(anotherTool);
+ * ```
+ */
 export class LuaSkill {
     /**
-     * Creates a new LuaSkill instance
+     * Creates a new LuaSkill instance.
      *
      * @param config - Configuration object containing skill metadata
+     * @param config.name - Skill name (optional, defaults to 'unnamed-skill')
+     * @param config.version - Skill version (optional, defaults to '1.0.0')
      * @param config.description - Short description of what the skill does (1-2 sentences)
      * @param config.context - Detailed explanation of how the agent should use the tools
-     *
-     * @example
-     * ```typescript
-     * const skill = new LuaSkill({
-     *   description: "Weather and calculator utilities",
-     *   context: "This skill provides weather information for any city and basic mathematical operations. Use get_weather for current conditions and calculator for arithmetic operations."
-     * });
-     * ```
+     * @param config.tools - Optional array of tools to add immediately
      */
     constructor(config) {
         this.tools = [];
@@ -74,11 +99,24 @@ export class LuaSkill {
             this.addTools(config.tools);
         }
     }
+    /**
+     * Adds a single tool to the skill.
+     * Tool name is validated before being added.
+     *
+     * @param tool - Tool to add
+     * @throws Error if tool name is invalid
+     */
     addTool(tool) {
-        // Validate the tool name before adding it
         assertValidToolName(tool.name);
         this.tools.push(tool);
     }
+    /**
+     * Adds multiple tools to the skill.
+     * All tool names are validated before being added.
+     *
+     * @param tools - Array of tools to add
+     * @throws Error if any tool name is invalid
+     */
     addTools(tools) {
         // Validate all tool names before adding them
         for (const tool of tools) {
@@ -86,6 +124,15 @@ export class LuaSkill {
         }
         this.tools.push(...tools);
     }
+    /**
+     * Executes a tool by name with provided input.
+     * Input is validated against the tool's Zod schema.
+     *
+     * @param input - Input object containing tool name and parameters
+     * @param input.tool - Name of the tool to execute
+     * @returns Promise resolving to tool execution result
+     * @throws Error if tool not found or input validation fails
+     */
     async run(input) {
         const tool = this.tools.find(tool => tool.name === input.tool);
         if (!tool) {

package/dist/types/tool-validation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tool Validation Utilities
+ * Validates tool names and other tool-related constraints
+ */
+/**
+ * Validates that a tool name contains only alphanumeric characters, hyphens, and underscores.
+ * No spaces or other special characters are allowed.
+ *
+ * This restriction ensures tool names:
+ * - Are compatible with all systems
+ * - Can be used in URLs and file paths
+ * - Are easy to reference in code
+ *
+ * Valid examples: "my-tool", "calculate_sum", "getTodo123"
+ * Invalid examples: "my tool", "calc@sum", "get.todo"
+ *
+ * @param name - Tool name to validate
+ * @returns True if name is valid, false otherwise
+ */
+export declare function validateToolName(name: string): boolean;
+/**
+ * Asserts that a tool name is valid, throwing an error if not.
+ * Use this when adding tools to ensure names are valid.
+ *
+ * @param name - Tool name to validate
+ * @throws Error if tool name is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidToolName('my-tool'); // OK
+ * assertValidToolName('my tool'); // Throws error
+ * ```
+ */
+export declare function assertValidToolName(name: string): void;

package/dist/types/tool-validation.js

@@ -0,0 +1,42 @@
+/**
+ * Tool Validation Utilities
+ * Validates tool names and other tool-related constraints
+ */
+/**
+ * Validates that a tool name contains only alphanumeric characters, hyphens, and underscores.
+ * No spaces or other special characters are allowed.
+ *
+ * This restriction ensures tool names:
+ * - Are compatible with all systems
+ * - Can be used in URLs and file paths
+ * - Are easy to reference in code
+ *
+ * Valid examples: "my-tool", "calculate_sum", "getTodo123"
+ * Invalid examples: "my tool", "calc@sum", "get.todo"
+ *
+ * @param name - Tool name to validate
+ * @returns True if name is valid, false otherwise
+ */
+export function validateToolName(name) {
+    const validNameRegex = /^[a-zA-Z0-9_-]+$/;
+    return validNameRegex.test(name);
+}
+/**
+ * Asserts that a tool name is valid, throwing an error if not.
+ * Use this when adding tools to ensure names are valid.
+ *
+ * @param name - Tool name to validate
+ * @throws Error if tool name is invalid
+ *
+ * @example
+ * ```typescript
+ * assertValidToolName('my-tool'); // OK
+ * assertValidToolName('my tool'); // Throws error
+ * ```
+ */
+export function assertValidToolName(name) {
+    if (!validateToolName(name)) {
+        throw new Error(`Invalid tool name "${name}". Tool names can only contain alphanumeric characters, ` +
+            `hyphens (-), and underscores (_). No spaces or other special characters are allowed.`);
+    }
+}

package/dist/utils/auth-flows.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Authentication Flow Utilities
+ * Handles different authentication methods (API key and email OTP)
+ */
+/**
+ * Handles API key authentication flow.
+ * Prompts for API key, validates it, and saves it securely.
+ *
+ * @returns Promise that resolves when authentication is complete
+ * @throws Error if API key is invalid
+ */
+export declare function handleApiKeyAuth(): Promise<void>;
+/**
+ * Handles email authentication flow with OTP verification.
+ * Sends OTP to email, verifies it, generates API key, and saves it.
+ *
+ * @returns Promise that resolves when authentication is complete
+ * @throws Error if OTP sending fails, verification fails, or API key generation fails
+ */
+export declare function handleEmailAuth(): Promise<void>;
+/**
+ * Prompts user to choose authentication method.
+ *
+ * @returns Selected authentication method ('api-key' or 'email')
+ */
+export declare function promptAuthMethod(): Promise<'api-key' | 'email'>;

package/dist/utils/auth-flows.js

@@ -0,0 +1,141 @@
+/**
+ * Authentication Flow Utilities
+ * Handles different authentication methods (API key and email OTP)
+ */
+import inquirer from "inquirer";
+import { saveApiKey, checkApiKey, requestEmailOTP, verifyOTPAndGetToken, generateApiKey } from "../services/auth.js";
+import { clearPromptLines, writeProgress, writeSuccess } from "./cli.js";
+/**
+ * Configuration for OTP verification
+ */
+const OTP_CONFIG = {
+    MAX_ATTEMPTS: 3,
+    OTP_LENGTH: 6,
+};
+/**
+ * Handles API key authentication flow.
+ * Prompts for API key, validates it, and saves it securely.
+ *
+ * @returns Promise that resolves when authentication is complete
+ * @throws Error if API key is invalid
+ */
+export async function handleApiKeyAuth() {
+    const answers = await inquirer.prompt([
+        {
+            type: "password",
+            name: "apiKey",
+            message: "Enter your API key",
+            mask: "*",
+        },
+    ]);
+    const data = await checkApiKey(answers.apiKey);
+    if (!data) {
+        throw new Error("Invalid API key");
+    }
+    await saveApiKey(answers.apiKey);
+    writeSuccess("✅ API key saved securely.");
+}
+/**
+ * Handles email authentication flow with OTP verification.
+ * Sends OTP to email, verifies it, generates API key, and saves it.
+ *
+ * @returns Promise that resolves when authentication is complete
+ * @throws Error if OTP sending fails, verification fails, or API key generation fails
+ */
+export async function handleEmailAuth() {
+    // Step 1: Collect email
+    const { email } = await inquirer.prompt([
+        {
+            type: "input",
+            name: "email",
+            message: "Enter your email address:",
+            validate: (input) => {
+                const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+                return emailRegex.test(input) || "Please enter a valid email address";
+            }
+        }
+    ]);
+    clearPromptLines(2);
+    // Step 2: Send OTP
+    writeProgress("📧 Sending OTP to your email...");
+    const otpSent = await requestEmailOTP(email);
+    if (!otpSent) {
+        throw new Error("Failed to send OTP. Please try again.");
+    }
+    writeProgress("✅ OTP sent successfully!");
+    // Step 3: Verify OTP with retry logic
+    const signInToken = await verifyOTPWithRetry(email);
+    // Step 4: Generate API key
+    writeProgress("🔑 Generating API key...");
+    const apiKey = await generateApiKey(signInToken);
+    if (!apiKey) {
+        throw new Error("Failed to generate API key. Please try again.");
+    }
+    // Step 5: Save API key
+    await saveApiKey(apiKey);
+    writeSuccess("✅ API key generated and saved securely.");
+}
+/**
+ * Verifies OTP with retry logic.
+ * Allows multiple attempts to enter the correct OTP.
+ *
+ * @param email - Email address for OTP verification
+ * @returns Sign-in token from successful verification
+ * @throws Error if maximum attempts are exceeded
+ */
+async function verifyOTPWithRetry(email) {
+    let otpVerified = false;
+    let attempts = 0;
+    let signInToken = null;
+    while (!otpVerified && attempts < OTP_CONFIG.MAX_ATTEMPTS) {
+        const { pin } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "pin",
+                message: "Enter the OTP code:",
+                validate: (input) => {
+                    return input.length === OTP_CONFIG.OTP_LENGTH || `OTP must be ${OTP_CONFIG.OTP_LENGTH} digits`;
+                }
+            }
+        ]);
+        clearPromptLines(2);
+        writeProgress("🔐 Verifying OTP...");
+        signInToken = await verifyOTPAndGetToken(email, pin);
+        if (signInToken) {
+            otpVerified = true;
+            writeProgress("✅ OTP verified successfully!");
+        }
+        else {
+            attempts++;
+            if (attempts < OTP_CONFIG.MAX_ATTEMPTS) {
+                console.log(`❌ Invalid OTP. ${OTP_CONFIG.MAX_ATTEMPTS - attempts} attempts remaining.`);
+            }
+            else {
+                throw new Error("Invalid OTP. Maximum attempts reached. Please try again later.");
+            }
+        }
+    }
+    if (!signInToken) {
+        throw new Error("OTP verification failed");
+    }
+    return signInToken;
+}
+/**
+ * Prompts user to choose authentication method.
+ *
+ * @returns Selected authentication method ('api-key' or 'email')
+ */
+export async function promptAuthMethod() {
+    const { authMethod } = await inquirer.prompt([
+        {
+            type: "list",
+            name: "authMethod",
+            message: "Choose authentication method:",
+            choices: [
+                { name: "API Key", value: "api-key" },
+                { name: "Email", value: "email" }
+            ]
+        }
+    ]);
+    return authMethod;
+}

package/dist/utils/bundling.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bundling Utilities
+ * Handles esbuild bundling of tools and main index
+ */
+import { ToolInfo } from '../interfaces/compile.js';
+import { Project } from "ts-morph";
+/**
+ * Bundles a tool's TypeScript code into a standalone JavaScript file.
+ * Uses esbuild to:
+ * - Bundle all dependencies (except external packages)
+ * - Minify code for production
+ * - Wrap for VM execution
+ *
+ * @param tool - The tool to bundle
+ * @param distDir - The distribution directory for output
+ */
+export declare function bundleTool(tool: ToolInfo, distDir: string): Promise<void>;
+/**
+ * Bundles the main index.ts file into a standalone JavaScript file.
+ * This creates the entry point for the skill.
+ *
+ * @param indexPath - Path to the index.ts file
+ * @param distDir - The distribution directory for output
+ */
+export declare function bundleMainIndex(indexPath: string, distDir: string): Promise<void>;
+/**
+ * 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
+ *
+ * @param tool - The tool to extract metadata from (mutated with executeCode and inputSchema)
+ * @param project - The ts-morph Project instance for AST analysis
+ */
+export declare function extractExecuteCode(tool: ToolInfo, project: Project): Promise<void>;

package/dist/utils/bundling.js

@@ -0,0 +1,137 @@
+/**
+ * Bundling Utilities
+ * Handles esbuild bundling of tools and main index
+ */
+import fs from "fs";
+import path from "path";
+import { build } from "esbuild";
+import { writeProgress } from "./cli.js";
+import { COMPILE_DIRS, COMPILE_FILES, ESBUILD_TOOL_CONFIG, ESBUILD_INDEX_CONFIG, DEFAULT_INPUT_SCHEMA, } from '../config/compile.constants.js';
+import { wrapToolForVM, createExecuteFunction, evaluateZodSchemaToJsonSchema, } from './compile.js';
+/**
+ * Bundles a tool's TypeScript code into a standalone JavaScript file.
+ * Uses esbuild to:
+ * - Bundle all dependencies (except external packages)
+ * - Minify code for production
+ * - Wrap for VM execution
+ *
+ * @param tool - The tool to bundle
+ * @param distDir - The distribution directory for output
+ */
+export async function bundleTool(tool, distDir) {
+    writeProgress(`📦 Bundling ${tool.className}...`);
+    try {
+        const outputPath = path.join(distDir, COMPILE_DIRS.TOOLS, `${tool.className}.js`);
+        await build({
+            ...ESBUILD_TOOL_CONFIG,
+            entryPoints: [tool.filePath],
+            outfile: outputPath,
+        });
+        // Wrap the bundled code for VM execution environment
+        await wrapToolForVM(outputPath, tool);
+    }
+    catch (error) {
+        console.warn(`Warning: Failed to bundle ${tool.className}:`, error);
+    }
+}
+/**
+ * Bundles the main index.ts file into a standalone JavaScript file.
+ * This creates the entry point for the skill.
+ *
+ * @param indexPath - Path to the index.ts file
+ * @param distDir - The distribution directory for output
+ */
+export async function bundleMainIndex(indexPath, distDir) {
+    writeProgress("📦 Bundling main index...");
+    try {
+        await build({
+            ...ESBUILD_INDEX_CONFIG,
+            entryPoints: [indexPath],
+            outfile: path.join(distDir, COMPILE_FILES.INDEX_JS),
+        });
+    }
+    catch (error) {
+        console.warn("Warning: Failed to bundle main index:", error);
+    }
+}
+/**
+ * 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
+ *
+ * @param tool - The tool to extract metadata from (mutated with executeCode and inputSchema)
+ * @param project - The ts-morph Project instance for AST analysis
+ */
+export async function extractExecuteCode(tool, project) {
+    try {
+        const toolSourceFile = project.getSourceFile(tool.filePath);
+        if (!toolSourceFile) {
+            console.warn(`Warning: Could not find source file for ${tool.className}`);
+            return;
+        }
+        const classDecl = toolSourceFile.getClass(tool.className);
+        if (!classDecl) {
+            console.warn(`Warning: Could not find class ${tool.className} in ${tool.filePath}`);
+            return;
+        }
+        // Verify execute method exists
+        const executeMethod = classDecl.getMethod('execute');
+        if (!executeMethod) {
+            console.warn(`Warning: Could not find execute method in ${tool.className}`);
+            return;
+        }
+        const executeBody = executeMethod.getBodyText();
+        if (!executeBody) {
+            console.warn(`Warning: Execute method has no body in ${tool.className}`);
+            return;
+        }
+        // Extract execute code from bundled file
+        tool.executeCode = extractExecuteCodeFromBundledFile(tool);
+        // Extract and convert input schema
+        tool.inputSchema = await extractInputSchema(classDecl, tool);
+    }
+    catch (error) {
+        console.warn(`Warning: Could not extract execute code for ${tool.className}:`, error);
+    }
+}
+/**
+ * Extracts execute code from the bundled tool file.
+ *
+ * @param tool - The tool whose bundled code to read
+ * @returns The execute function code or undefined if not found
+ */
+function extractExecuteCodeFromBundledFile(tool) {
+    const bundledPath = path.join(process.cwd(), COMPILE_DIRS.DIST, COMPILE_DIRS.TOOLS, `${tool.className}.js`);
+    if (fs.existsSync(bundledPath)) {
+        const bundledCode = fs.readFileSync(bundledPath, 'utf8');
+        return createExecuteFunction(bundledCode, tool);
+    }
+    return undefined;
+}
+/**
+ * Extracts and converts the input schema from a tool class.
+ * Converts Zod schemas to JSON Schema format.
+ *
+ * @param classDecl - The tool class declaration from ts-morph
+ * @param tool - The tool being analyzed (for logging)
+ * @returns The JSON Schema object or default schema
+ */
+async function extractInputSchema(classDecl, tool) {
+    const inputSchemaProperty = classDecl.getProperty('inputSchema');
+    if (inputSchemaProperty && inputSchemaProperty.getInitializer()) {
+        const initializer = inputSchemaProperty.getInitializer();
+        if (initializer) {
+            try {
+                const zodSchemaCode = initializer.getText();
+                return await evaluateZodSchemaToJsonSchema(zodSchemaCode);
+            }
+            catch (error) {
+                console.warn(`Warning: Could not parse Zod schema for ${tool.className}:`, error);
+                return DEFAULT_INPUT_SCHEMA;
+            }
+        }
+    }
+    return DEFAULT_INPUT_SCHEMA;
+}

package/dist/utils/compile.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Utility functions for compile command
+ */
+import { Project } from "ts-morph";
+import { ToolInfo } from "../interfaces/compile.js";
+/**
+ * Compresses code using gzip and returns base64 encoded string
+ */
+export declare function compressCode(code: string): string;
+/**
+ * Finds the index.ts file in the project
+ */
+export declare function findIndexFile(): string;
+/**
+ * Resolves import path from module specifier
+ */
+export declare function resolveImportPath(moduleSpecifier: string, currentFilePath: string): string;
+/**
+ * Creates execute function wrapper from bundled code
+ */
+export declare function createExecuteFunction(bundledCode: string, tool: ToolInfo): string;
+/**
+ * Evaluates Zod schema code and converts it to JSON Schema
+ */
+export declare function evaluateZodSchemaToJsonSchema(zodSchemaCode: string): Promise<any>;
+/**
+ * Wraps bundled tool code for VM execution
+ */
+export declare function wrapToolForVM(outputPath: string, tool: ToolInfo): Promise<void>;
+/**
+ * Extracts tool information from a new expression in the AST
+ */
+export declare function extractToolFromNewExpressionSync(newExpr: any, project: Project): ToolInfo | null;
+/**
+ * Extracts skills metadata from index file
+ */
+export declare function extractSkillsMetadata(indexFile: any): any[];