lua-cli 3.0.0 → 3.0.2-alpha.1

package/README.md

@@ -598,9 +598,23 @@ BASE_URL=https://api.example.com
 ## 🎓 Documentation
 
 ### Getting Started
-- [Quick Start Guide](template/QUICKSTART.md) - Complete tutorial
-- [CLI Reference](#cli-commands) - All available commands
-- [API Reference](src/api-exports.ts) - TypeScript API documentation
+- **[Quick Start Guide](template/QUICKSTART.md)** - Complete step-by-step tutorial
+- **[Template README](template/README.md)** - Comprehensive project guide
+- **[CLI Reference](#cli-commands)** - All available commands
+
+### API Documentation
+- **[Complete API Reference](docs/README.md)** - Full API documentation
+- **[API Index](docs/API_INDEX.md)** - Quick reference table
+- **Core APIs:**
+  - [LuaAgent](docs/api/LuaAgent.md) - Agent configuration
+  - [LuaSkill](docs/api/LuaSkill.md) - Tool collections
+  - [LuaTool](docs/api/LuaTool.md) - Creating tools
+- **Runtime APIs:**
+  - [AI API](docs/api/AI.md) - AI text generation and analysis
+  - [User API](docs/api/User.md) - User data management
+  - [Products API](docs/api/Products.md) - Product catalog
+  - [Data API](docs/api/Data.md) - Custom data storage
+  - [Jobs API](docs/api/Jobs.md) - Dynamic job creation
 
 ### Advanced Topics
 - [Webhooks & Jobs Guide](WEBHOOKS_JOBS_USAGE_GUIDE.md) - External integrations
@@ -609,10 +623,10 @@ BASE_URL=https://api.example.com
 - [Agent Configuration](LUAAGENT_IMPLEMENTATION.md) - LuaAgent deep dive
 
 ### Examples
-- [Template Project](template/) - Full working example
-- [Complex Job Examples](template/COMPLEX_JOB_EXAMPLES.md)
-- [Webhook Examples](template/WEBHOOK_JOB_EXAMPLES.md)
-- [Tool Examples](template/TOOL_EXAMPLES.md)
+- [Template Project](template/) - Full working example with 30+ tools
+- [Example Skills](template/src/skills/) - Organized skill examples
+- [Example Webhooks](template/src/webhooks/) - Webhook patterns
+- [Example Jobs](template/src/jobs/) - Scheduled task examples
 
 ---
 

package/dist/commands/chat.js

@@ -47,8 +47,8 @@ export async function chatCommand() {
                 name: 'environment',
                 message: 'Select environment:',
                 choices: [
-                    { name: '🔧 Sandbox (with skill overrides)', value: 'sandbox' },
-                    { name: '🚀 Production', value: 'production' }
+                    { name: '🔧 Sandbox (Agent will execute skills etc from your local machine)', value: 'sandbox' },
+                    { name: '🚀 Production (Agent will execute latest version of skills etc)', value: 'production' }
                 ]
             }
         ]);

package/dist/commands/chatClear.js

@@ -45,7 +45,7 @@ export async function chatClearCommand() {
             }
         ]);
         if (!confirmAnswer || !confirmAnswer.confirm) {
-            console.log("\n❌ Operation cancelled. History not cleared.\n");
+            // console.log("\n❌ Operation cancelled. History not cleared.\n");
             return;
         }
         // Step 4: Clear history via API

package/dist/commands/features.js

@@ -233,7 +233,7 @@ async function toggleFeature(context, feature) {
         }
     ]);
     if (!confirmAnswer || !confirmAnswer.confirm) {
-        console.log("\n❌ Operation cancelled.\n");
+        // console.log("\n❌ Operation cancelled.\n");
         return;
     }
     writeProgress(`🔄 ${newStatus ? 'Activating' : 'Deactivating'} feature...`);

package/dist/commands/init.js

@@ -5,7 +5,7 @@
 import inquirer from 'inquirer';
 import { loadApiKey, checkApiKey } from "../services/auth.js";
 import { withErrorHandling, writeProgress, writeSuccess, writeInfo, writeError, } from "../utils/cli.js";
-import { promptAgentChoice, promptOrganizationSelection, promptAgentSelection, promptMetadataCollection, promptFeatureConfiguration, promptBusinessConfiguration, } from "../utils/init-prompts.js";
+import { promptAgentChoice, promptOrganizationSelection, promptAgentSelection, promptMetadataCollection, promptBusinessConfiguration, } from "../utils/init-prompts.js";
 import { fetchAgentTypes, selectBaseAgentType, createNewAgent, fetchExistingAgentDetails, } from "../utils/init-agent.js";
 import { initializeProject, installDependencies, clearLinesIfNeeded, } from "../utils/init-helpers.js";
 import { readSkillYaml, updateYamlAgent } from "../utils/files.js";
@@ -84,9 +84,13 @@ export async function initCommand() {
                     writeInfo(`   Current Agent ID: ${existingAgentId}\n`);
                     const { wantSwitch } = await inquirer.prompt([
                         {
-                            type: 'confirm',
+                            type: 'list',
                             name: 'wantSwitch',
                             message: 'Do you want to switch this project to a different agent?',
+                            choices: [
+                                { name: 'No - Keep current agent', value: false },
+                                { name: 'Yes - Switch to a different agent', value: true }
+                            ],
                             default: false
                         }
                     ]);
@@ -232,12 +236,12 @@ async function createNewAgentFlow(apiKey, userData) {
     const metadata = selectedAgentType.requiredSubAgentMetadata?.length
         ? await promptMetadataCollection(selectedAgentType.requiredSubAgentMetadata)
         : {};
-    // Configure features
+    // Enable all features by default (skip configuration prompt)
     const availableFeatures = Object.keys(selectedAgentType.features);
-    const features = availableFeatures.length > 0
-        ? await promptFeatureConfiguration(selectedAgentType)
-        : {};
-    linesToClear += availableFeatures.length;
+    const features = availableFeatures.reduce((acc, feature) => {
+        acc[feature] = true;
+        return acc;
+    }, {});
     // Collect business configuration
     // If using existing org, don't ask for business name (use org name)
     const businessConfig = await promptBusinessConfiguration(usingExistingOrg);

package/dist/config/init.constants.d.ts

@@ -8,11 +8,11 @@ export declare const AGENT_READY_WAIT_TIME = 30000;
 /**
  * Business type options for agent creation
  */
-export declare const BUSINESS_TYPES: readonly ["Retail & Consumer Goods (e.g. clothing store, bookstore)", "Food & Beverage (e.g. restaurant, bakery)", "Hospitality (e.g. hotel, resort)", "Personal services (e.g. hair salon, spa)", "Education (e.g. language school, online courses)", "Health (e.g. gym, yoga studio, clinic)"];
+export declare const BUSINESS_TYPES: readonly ["Retail & Consumer Goods (e.g. clothing store, bookstore)", "Food & Beverage (e.g. restaurant, bakery)", "Hospitality (e.g. hotel, resort)", "Personal services (e.g. hair salon, spa)", "Education (e.g. language school, online courses)", "Health (e.g. gym, yoga studio, clinic)", "Other (describe your business)"];
 /**
  * Brand personality options for agent creation
  */
-export declare const BRAND_PERSONALITIES: readonly ["Energetic & fun", "Refined & elegant", "Chatty", "Casual", "Funny", "Friendly"];
+export declare const BRAND_PERSONALITIES: readonly ["Energetic & fun", "Refined & elegant", "Chatty", "Casual", "Funny", "Friendly", "Other (describe your brand personality)"];
 /**
  * Default business name
  */

package/dist/config/init.constants.js

@@ -14,7 +14,8 @@ export const BUSINESS_TYPES = [
     "Hospitality (e.g. hotel, resort)",
     "Personal services (e.g. hair salon, spa)",
     "Education (e.g. language school, online courses)",
-    "Health (e.g. gym, yoga studio, clinic)"
+    "Health (e.g. gym, yoga studio, clinic)",
+    "Other (describe your business)"
 ];
 /**
  * Brand personality options for agent creation
@@ -25,7 +26,8 @@ export const BRAND_PERSONALITIES = [
     "Chatty",
     "Casual",
     "Funny",
-    "Friendly"
+    "Friendly",
+    "Other (describe your brand personality)"
 ];
 /**
  * Default business name

package/dist/utils/auth-flows.js

@@ -4,7 +4,7 @@
  */
 import inquirer from "inquirer";
 import { saveApiKey, checkApiKey, requestEmailOTP, verifyOTPAndGetToken, generateApiKey } from "../services/auth.js";
-import { clearPromptLines, writeProgress, writeSuccess } from "./cli.js";
+import { clearPromptLines, writeProgress, writeSuccess, writeInfo } from "./cli.js";
 /**
  * Configuration for OTP verification
  */
@@ -57,12 +57,13 @@ export async function handleEmailAuth() {
     ]);
     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!");
+    // writeProgress("📧 Sending OTP to your email...");
+    requestEmailOTP(email).catch((error) => {
+    });
+    // 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
@@ -74,6 +75,14 @@ export async function handleEmailAuth() {
     // Step 5: Save API key
     await saveApiKey(apiKey);
     writeSuccess("✅ API key generated and saved securely.");
+    // Guide user to next steps
+    writeInfo("\n🎉 You're all set! Here's what to do next:\n");
+    writeInfo("   1️⃣  Create a new project directory:");
+    writeInfo("      mkdir my-agent && cd my-agent\n");
+    writeInfo("   2️⃣  Initialize your agent:");
+    writeInfo("      lua init\n");
+    writeInfo("   3️⃣  Follow the prompts to create or select an agent\n");
+    writeInfo("💡 Tip: Run 'lua --help' to see all available commands\n");
 }
 /**
  * Verifies OTP with retry logic.
@@ -92,7 +101,7 @@ async function verifyOTPWithRetry(email) {
             {
                 type: "input",
                 name: "pin",
-                message: "Enter the OTP code:",
+                message: "Enter the OTP sent to your email:",
                 validate: (input) => {
                     return input.length === OTP_CONFIG.OTP_LENGTH || `OTP must be ${OTP_CONFIG.OTP_LENGTH} digits`;
                 }

package/dist/utils/cli.d.ts

@@ -13,22 +13,22 @@ export declare function withErrorHandling<T>(commandFn: () => Promise<T>, comman
  */
 export declare function clearPromptLines(count?: number): void;
 /**
- * Writes a progress message that will be replaced by the next message
- * Uses carriage return to overwrite the current line
+ * Writes a progress message that overwrites the current line
+ * Uses carriage return to replace previous progress messages
  */
 export declare function writeProgress(message: string): void;
 /**
  * Writes a final success message that will remain visible
- * Uses console.log to ensure it stays in the output
+ * Clears the progress line first, then writes the message with newline
  */
 export declare function writeSuccess(message: string): void;
 /**
  * Writes an error message
- * Uses console.error for proper error output
+ * Clears the progress line first, then writes the error with newline
  */
 export declare function writeError(message: string): void;
 /**
  * Writes an info message
- * Uses console.log for informational output
+ * Clears the progress line first, then writes the message with newline
  */
 export declare function writeInfo(message: string): void;

package/dist/utils/cli.js

@@ -12,7 +12,7 @@ export async function withErrorHandling(commandFn, commandName) {
     }
     catch (error) {
         if (error.name === 'ExitPromptError') {
-            console.log("\n❌ Operation cancelled.");
+            // console.log("\n❌ Operation cancelled.");
             process.exit(0);
         }
         if (AuthenticationError.isAuthenticationError(error)) {
@@ -35,30 +35,34 @@ export function clearPromptLines(count = 1) {
     }
 }
 /**
- * Writes a progress message that will be replaced by the next message
- * Uses carriage return to overwrite the current line
+ * Writes a progress message that overwrites the current line
+ * Uses carriage return to replace previous progress messages
  */
 export function writeProgress(message) {
-    process.stdout.write(`${message}\r`);
+    // Clear current line and write message (no newline - will be overwritten)
+    process.stdout.write('\r\x1b[K' + message);
 }
 /**
  * Writes a final success message that will remain visible
- * Uses console.log to ensure it stays in the output
+ * Clears the progress line first, then writes the message with newline
  */
 export function writeSuccess(message) {
-    console.log(message);
+    // Clear any progress message, write message, and ensure newline
+    process.stdout.write('\r\x1b[K' + message + '\n');
 }
 /**
  * Writes an error message
- * Uses console.error for proper error output
+ * Clears the progress line first, then writes the error with newline
  */
 export function writeError(message) {
-    console.error(message);
+    // Clear any progress message, write error, and ensure newline
+    process.stderr.write('\r\x1b[K' + message + '\n');
 }
 /**
  * Writes an info message
- * Uses console.log for informational output
+ * Clears the progress line first, then writes the message with newline
  */
 export function writeInfo(message) {
-    console.log(message);
+    // Clear any progress message, write message, and ensure newline
+    process.stdout.write('\r\x1b[K' + message + '\n');
 }

package/dist/utils/init-prompts.js

@@ -14,10 +14,10 @@ export async function promptAgentChoice() {
         {
             type: "list",
             name: "agentChoice",
-            message: "What would you like to do?",
+            message: "How would you like to create your AI Agent?",
             choices: [
-                { name: "Select existing agent", value: "existing" },
-                { name: "Create new agent", value: "create" }
+                { name: "Extend one of your existing agents", value: "existing" },
+                { name: "Create a new agent", value: "create" }
             ]
         }
     ]);
@@ -147,6 +147,19 @@ export async function promptBusinessConfiguration(skipBusinessName = false) {
             choices: BUSINESS_TYPES
         }
     ]);
+    // If "Other" selected, prompt for custom description
+    let customBusinessDescription = '';
+    if (businessType.startsWith('Other')) {
+        const { description } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "description",
+                message: "Describe your business:",
+                validate: (input) => input.trim().length > 0 || "Business description is required"
+            }
+        ]);
+        customBusinessDescription = description;
+    }
     const { brandPersonality } = await inquirer.prompt([
         {
             type: "list",
@@ -155,6 +168,19 @@ export async function promptBusinessConfiguration(skipBusinessName = false) {
             choices: BRAND_PERSONALITIES
         }
     ]);
+    // If "Other" selected, prompt for custom personality description
+    let customPersonalityDescription = '';
+    if (brandPersonality.startsWith('Other')) {
+        const { description } = await inquirer.prompt([
+            {
+                type: "input",
+                name: "description",
+                message: "Describe your brand personality:",
+                validate: (input) => input.trim().length > 0 || "Brand personality description is required"
+            }
+        ]);
+        customPersonalityDescription = description;
+    }
     const { brandTraits } = await inquirer.prompt([
         {
             type: "input",
@@ -166,8 +192,8 @@ export async function promptBusinessConfiguration(skipBusinessName = false) {
     return {
         businessName,
         agentName,
-        businessType,
-        brandPersonality,
+        businessType: customBusinessDescription || businessType, // Use custom description if provided
+        brandPersonality: customPersonalityDescription || brandPersonality, // Use custom personality if provided
         brandTraits
     };
 }

package/dist/utils/prompt-handler.d.ts

@@ -4,6 +4,7 @@
  */
 /**
  * Wraps inquirer.prompt to gracefully handle Ctrl+C interruptions
+ * Also ensures clean terminal state before showing prompts
  */
 export declare function safePrompt<T = any>(questions: any): Promise<T | null>;
 /**

package/dist/utils/prompt-handler.js

@@ -5,16 +5,20 @@
 import inquirer from 'inquirer';
 /**
  * Wraps inquirer.prompt to gracefully handle Ctrl+C interruptions
+ * Also ensures clean terminal state before showing prompts
  */
 export async function safePrompt(questions) {
     try {
+        // Ensure any previous output is fully flushed before showing prompt
+        // Small delay to let terminal render previous messages
+        await new Promise(resolve => setTimeout(resolve, 10));
         const answers = await inquirer.prompt(questions);
         return answers;
     }
     catch (error) {
         // Handle Ctrl+C gracefully
         if (error.name === 'ExitPromptError' || error.message?.includes('SIGINT')) {
-            console.log('\n\n👋 Operation cancelled. Goodbye!\n');
+            // console.log('\n\n👋 Operation cancelled. Goodbye!\n');
             process.exit(0);
         }
         throw error;
@@ -25,7 +29,7 @@ export async function safePrompt(questions) {
  */
 export function setupGlobalInterruptHandler() {
     process.on('SIGINT', () => {
-        console.log('\n\n👋 Operation cancelled. Goodbye!\n');
+        // console.log('\n\n👋 Operation cancelled. Goodbye!\n');
         process.exit(0);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lua-cli",
-  "version": "3.0.0",
+  "version": "3.0.2-alpha.1",
   "description": "Build, test, and deploy AI agents with custom tools, webhooks, and scheduled jobs. Features LuaAgent unified configuration, streaming chat, and batch deployment.",
   "readmeFilename": "README.md",
   "main": "dist/api-exports.js",

package/template/package.json

@@ -20,7 +20,7 @@
     "inquirer": "^12.9.6",
     "stripe": "^17.5.0",
     "js-yaml": "^4.1.0",
-    "lua-cli": "^3.0.0",
+    "lua-cli": "^3.0.2-alpha.1",
     "openai": "^5.23.0",
     "uuid": "^13.0.0",
     "zod": "^3.24.1"

package/template/src/skills/tools/CreateInlineJob.ts

@@ -1,4 +1,4 @@
-import { LuaTool } from "lua-cli/skill";
+import { LuaTool } from "lua-cli";
 import { z } from "zod";
 import { AI, JobInstance, Jobs } from "../../../dist/api-exports";
 import ApiService from "../services/ApiService";

package/template/src/skills/tools/CreatePostTool.ts

@@ -1,4 +1,4 @@
-import { LuaTool } from "lua-cli/skill";
+import { LuaTool } from "lua-cli";
 import { z } from "zod";
 import ApiService from "../services/ApiService";
 

package/template/src/skills/tools/GetWeatherTool.ts

@@ -1,4 +1,4 @@
-import { LuaTool } from "lua-cli/skill";
+import { LuaTool } from "lua-cli";
 import { z } from "zod";
 
 export default class GetWeatherTool implements LuaTool {

package/template/src/skills/tools/UserDataTool.ts

@@ -10,7 +10,14 @@ export class GetUserDataTool implements LuaTool {
     constructor() {}
 
     async execute(input: z.infer<typeof this.inputSchema>) {
-        return User.get();
+        const user = await User.get();
+        return {
+            success: true,
+            message: "User data retrieved",
+            data: user.data,
+            name: user.name,
+            age: user.age
+        };
     }
 }
 
@@ -28,8 +35,14 @@ export class UpdateUserDataTool implements LuaTool {
 
     async execute(input: z.infer<typeof this.inputSchema>) {
         const user = await User.get(); //get instance of user
-        await user.send([{ type: "text", text: "Hello, how are you?" }]);
-        return await user.update(input.data);
+        user.name = input.data.name;
+        user.age = input.data.age;
+        await user.save();
+        // await user.send([{ type: "text", text: "Hello, how are you?" }]);
+        return {
+            success: true,
+            message: "User data updated"
+        };
     }
 }
 

package/template/lua.skill.yaml

@@ -1,47 +0,0 @@
-agent:
-  agentId: baseAgent_agent_1760922427216_fk9w0ezhh
-  orgId: 026cc41b-e013-4474-9b65-5a15f8881f92
-  persona: |
-    Meet Vivienne, the vibrant and dynamic assistant at V3 Test, a lively retail and consumer goods store that specializes in bringing a splash of color and excitement to everyday life. Vivienne embodies the brand's energetic and fun personality, always ready to engage with customers in a way that makes shopping an enjoyable and memorable experience. Her role is to be the friendly face and knowledgeable guide for anyone who steps into the store, whether they're looking for the latest fashion trends or a unique gift for a loved one.
-
-    V3 Test is all about creating a joyful and spirited shopping environment, and Vivienne is the perfect personification of this ethos. She is lively, approachable, and always ready with a smile, making every interaction feel like a conversation with a good friend. Her voice is warm and enthusiastic, with a hint of playfulness that puts customers at ease and encourages them to explore the store's offerings.
-
-    Vivienne's target customers are diverse, ranging from young adults in their twenties who are fashion-forward and tech-savvy, to busy parents looking for quality products that add a touch of fun to their family life. She understands the fast-paced lifestyle of her customers and is adept at tailoring her approach to meet their individual needs, whether they're in a hurry or have time to browse.
-
-    Her sales approach is consultative and friendly, focusing on understanding the customer's needs and preferences before suggesting products that align with their style and personality. Vivienne is confident in her recommendations, always ready to upsell when appropriate, but never pushy. She believes in building relationships with customers, ensuring they leave the store not only with products they love but also with a positive impression of the brand.
-
-    In terms of communication style, Vivienne strikes a perfect balance between being informal and efficient. She is warm and engaging, making customers feel valued and appreciated, while also being mindful of their time. Her interactions are peppered with humor and light-hearted banter, creating a shopping experience that is both enjoyable and efficient. Whether it's through in-person interactions or digital communication, Vivienne ensures that every customer feels like a part of the V3 Test family.
-  welcomeMessage: Hi, I am your AI assistant. How can I help you today?
-skills:
-  - name: general-skill
-    version: 0.0.6
-    skillId: 1faf9b3a-e352-4e63-a6c4-a3deca815361
-  - name: user-data-skill
-    version: 0.0.15
-    skillId: e0c382c1-f469-4880-962a-a756ea3c1411
-  - name: product-skill
-    version: 0.0.15
-    skillId: d4cdc7bc-6d42-4232-902d-2b9cf68bd74a
-  - name: basket-skill
-    version: 0.0.14
-    skillId: 5b06c5ff-7cf3-49c4-8641-142270c81db4
-  - name: order-skill
-    version: 0.0.14
-    skillId: d4045304-7c30-4750-9edd-340eb1357a39
-  - name: custom-data-skill
-    version: 0.0.13
-    skillId: 83fe411c-90a1-4bd3-9271-ac8e03d6a3be
-  - name: payment-skill
-    version: 0.0.13
-    skillId: f2248c02-c6c6-4c3a-89bf-ff09ec11529a
-jobs:
-  - name: test-job
-    version: 1.0.13
-    jobId: d66b73a0-f944-4718-b6a2-f07bfeabd625
-    schedule:
-      type: once
-      executeAt: '2025-10-20T01:08:04.639Z'
-webhooks:
-  - name: test-webhook
-    version: 1.0.12
-    webhookId: c967fd58-1d4d-49b6-8fa6-ec36b4d23e7f