lua-cli 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0-alpha.1] - 2024-12-19
+
+### Added
+- **Centralized CLI Utilities**: New `src/utils/cli.ts` module for consistent error handling and output management
+- **Command Restructuring**: Reorganized commands into logical groups:
+  - `lua auth` - Authentication management (configure, logout, key)
+  - `lua skill` - Skill development (init, compile, test, push, dev, deploy)
+- **Enhanced Error Handling**: Graceful handling of Ctrl+C (SIGINT) across all commands
+- **Consistent Output Management**: Standardized progress messages, success messages, and prompt clearing
+- **Tool Name Validation**: Regex-based validation for tool names (alphanumeric, hyphens, underscores only)
+- **Version Management**: TOML-based version tracking with automatic versioning
+- **Skill Push/Deploy/Dev**: New commands for version management, sandbox development, and production deployment
+- **Smart Sandbox Management**: Dev command intelligently reuses existing sandbox skill IDs and falls back to creating new ones when needed
+- **File Watching Mode**: Dev command now watches for file changes and automatically recompiles and pushes to sandbox
+- **Web Chat Interface**: Dev command now includes a beautiful web-based chat interface for real-time skill testing
+- **Live Log Panel**: Real-time log feed with WebSocket connection for monitoring execution details
+- **Log Details Support**: Enhanced log display with detailed information sections and proper error handling
+- **Comprehensive Testing**: 100% test coverage for CLI utilities with 44 passing tests
+
+### Changed
+- **Command Structure**: 
+  - `lua configure` → `lua auth configure`
+  - `lua destroy` → `lua auth logout` 
+  - `lua apiKey` → `lua auth key`
+  - `lua init` → `lua skill init`
+  - `lua compile` → `lua skill compile`
+  - `lua test` → `lua skill test`
+  - Added `lua skill push`, `lua skill dev`, and `lua skill deploy`
+- **LuaSkill Constructor**: Now accepts object `{description, context}` instead of separate parameters
+- **TOML Configuration**: Added `version` and `skillId` fields to `lua.skill.toml`
+- **Error Messages**: Standardized format: `"❌ Error during [command]: [message]"`
+- **Output Consistency**: All commands now use centralized utilities for consistent UX
+
+### Technical Improvements
+- **Zero Code Duplication**: Centralized error handling eliminates repetitive code
+- **Professional UX**: Clean, consistent output with preserved command history
+- **Maintainable Architecture**: Single source of truth for CLI patterns
+- **Type Safety**: Enhanced TypeScript interfaces and validation
+- **Test Coverage**: Comprehensive test suite with 100% CLI utility coverage
+
+### Security
+- **Input Validation**: Tool name validation prevents injection attacks
+- **Graceful Cancellation**: Proper handling of user interruptions
+- **Error Isolation**: Centralized error handling prevents crashes
+
+### Documentation
+- **Updated README**: Reflects new command structure and features
+- **Developer Guide**: Enhanced documentation for LuaSkill constructor
+- **API Reference**: Updated examples and usage patterns
+
 ## [1.2.1] - 2024-09-19
 
 ### Fixed

package/README.md

@@ -27,21 +27,22 @@ lua --help
 - 🧪 **Interactive Testing**: Test your tools with real-time execution
 - 🚀 **Deployment**: Compile and deploy skills to the Lua platform
 - 🔑 **API Key Management**: Securely store, view, and manage your API keys
+- 💾 **User Data API**: Built-in API for persistent user data storage in your tools
 - 📚 **Comprehensive Documentation**: Complete guides and examples
 
 ## Quick Start
 
 1. **Configure your authentication:**
    ```bash
-   lua configure
+   lua auth configure
    ```
    Choose between API key or email authentication methods.
 
 2. **Initialize a new skill project:**
    ```bash
-   lua init
+   lua skill init
    ```
-   Select your organization and agent, then provide skill details.
+   Choose between selecting an existing agent or creating a new one, then provide skill details.
 
 3. **Develop your tools:**
    ```bash
@@ -51,25 +52,27 @@ lua --help
 
 4. **Compile your skill:**
    ```bash
-   lua compile
+   lua skill compile
    ```
    Bundles dependencies and creates deployable files.
 
 5. **Test your tools:**
    ```bash
-   lua test
+   lua skill test
    ```
    Interactive testing interface for your tools.
 
 6. **Deploy your skill:**
    ```bash
-   lua deploy
+   lua skill deploy
    ```
    Deploy to the Lua platform.
 
 ## Commands
 
-### `lua configure`
+### Authentication Commands
+
+#### `lua auth configure`
 
 Set up your authentication credentials. You can choose between:
 
@@ -77,55 +80,56 @@ Set up your authentication credentials. You can choose between:
 - **Email**: Email-based OTP authentication
 
 ```bash
-lua configure
-```
-
-### `lua init`
-
-Initialize a new Lua skill project in the current directory.
-
-```bash
-lua init
+lua auth configure
 ```
 
-This command will:
-- Fetch your organizations and agents from the API
-- Let you select an organization by name
-- Let you choose an agent from the selected organization
-- Prompt for skill name and description
-- Create a `lua.skill.toml` configuration file
-- Copy template files to the current directory
-
-### `lua apiKey`
+#### `lua auth key`
 
 Display your stored API key (with confirmation prompt).
 
 ```bash
-lua apiKey
+lua auth key
 ```
 
-### `lua agents`
+#### `lua auth logout`
 
-Fetch and display your agents from the HeyLua API.
+Delete your stored API key and credentials.
 
 ```bash
-lua agents
+lua auth logout
 ```
 
-### `lua destroy`
+### Skill Management Commands
 
-Delete your stored API key and credentials.
+#### `lua skill init`
+
+Initialize a new Lua skill project in the current directory.
 
 ```bash
-lua destroy
+lua skill init
 ```
 
-### `lua compile`
+This command will:
+- Fetch your organizations and agents from the API
+- Let you select an organization by name
+- **Choose between existing agents or creating a new one:**
+  - **Existing Agent**: Select from your current agents
+  - **New Agent**: Create a custom agent with:
+    - Agent type selection (Base Agent, Shopify, WooCommerce, etc.)
+    - Required metadata collection (API keys, IDs, etc.)
+    - Feature configuration (RAG, tickets, web search, etc.)
+    - Business information (name, type, personality, traits)
+    - Automatic persona generation and welcome message
+- Prompt for skill name and description
+- Create a `lua.skill.yaml` configuration file with agent details
+- Copy template files to the current directory
+
+#### `lua skill compile`
 
 Compile your LuaSkill and bundle all dependencies.
 
 ```bash
-lua compile
+lua skill compile
 ```
 
 This command will:
@@ -139,12 +143,12 @@ This command will:
 - `--watch` - Watch for changes and recompile automatically
 - `--minify` - Minify the bundled code
 
-### `lua test`
+#### `lua skill test`
 
 Interactive testing interface for your tools.
 
 ```bash
-lua test
+lua skill test
 ```
 
 Features:
@@ -154,23 +158,75 @@ Features:
 - Error reporting and debugging
 - Mock data support
 
-### `lua deploy`
+#### `lua skill push`
 
-Deploy your compiled skill to the Lua platform.
+Push your compiled skill version to the server.
 
 ```bash
-lua deploy
+lua skill push
 ```
 
+This command will:
+- Compile your skill first
+- Confirm the version you want to push
+- Send the compiled skill data to the server
+- Store the skill ID in your YAML file
+
+#### `lua skill dev`
+
+Push your compiled skill version to the sandbox for development and testing with automatic file watching and web chat interface.
+
+```bash
+lua skill dev
+```
+
+This command will:
+- Compile your skill first
+- Confirm the version you want to push to sandbox
+- **Smart Sandbox Management**:
+  - If you have a previous sandbox skill ID stored, it will try to update the existing sandbox
+  - If the update fails or no sandbox exists, it will create a new one
+  - The sandbox skill ID is securely stored on your machine for future use
+- Display the sandbox skill ID for testing
+- **Web Chat Interface**:
+  - Automatically opens a beautiful chat interface in your browser
+  - Test your sandbox skill in real-time with natural language
+  - Messages are sent to the sandbox environment via the chat API
+  - Available at `http://localhost:3000` (opens automatically)
+- **Live Log Panel**:
+  - Real-time log feed showing execution details
+  - WebSocket connection to `wss://api.lua.dev/feed`
+  - Console-style interface with color-coded log levels
+  - Shows tool calls, errors, metrics, and execution metadata
+  - Displays detailed information in expandable sections
+  - Connection status indicator and automatic reconnection
+  - Supports log types: error, debug, warn, info
+- **File Watching Mode**:
+  - Watches for file changes in the current directory
+  - Automatically recompiles and pushes to sandbox when files change
+  - Ignores build artifacts (`.lua/`, `node_modules/`, `.git/`, etc.)
+  - Debounces rapid changes to prevent excessive builds
+  - Press `Ctrl+C` to stop watching and exit
+
+#### `lua skill deploy`
+
+Deploy a version to production.
+
+```bash
+lua skill deploy
+```
+
+This command will:
+- Fetch available versions from the server
+- Let you select which version to deploy
+- Show a warning about deploying to all users
+- Publish the selected version to production
+
 **Requirements:**
-- Valid API key (configured with `lua configure`)
-- Compiled skill (run `lua compile` first)
+- Valid API key (configured with `lua auth configure`)
+- Compiled skill (run `lua skill compile` first)
 - Active internet connection
 
-**Output:**
-- Skill deployed to your selected agent
-- Deployment confirmation and status
-
 ## Template System
 
 The Lua CLI includes a comprehensive template system with examples and documentation:
@@ -225,30 +281,33 @@ template/
 
 ## Configuration File
 
-The `lua.skill.toml` file is created when you run `lua init`:
+The `lua.skill.yaml` file is created when you run `lua skill init`:
 
-```toml
-[agent]
-agentId = "your-agent-id"
-orgId = "your-organization-id"
+```yaml
+agent:
+  agentId: "your-agent-id"
+  orgId: "your-organization-id"
+  persona: "Generated persona description" # Only for newly created agents
+  welcomeMessage: "Welcome message" # Only for newly created agents
 
-[skill]
-name = "Your Skill Name"
-description = "Description of your skill"
+skill:
+  name: "Your Skill Name"
+  version: "0.0.1"
+  skillId: "your-skill-id"
 ```
 
 ## Authentication Methods
 
 ### API Key Authentication
 
-1. Run `lua configure`
+1. Run `lua auth configure`
 2. Select "API Key"
 3. Enter your API key when prompted
 4. The key is validated and stored securely
 
 ### Email Authentication
 
-1. Run `lua configure`
+1. Run `lua auth configure`
 2. Select "Email"
 3. Enter your email address
 4. Check your email for the OTP code
@@ -267,7 +326,7 @@ description = "Description of your skill"
 ### 1. Project Setup
 ```bash
 # Initialize a new skill project
-lua init
+lua skill init
 
 # Or copy the template
 cp -r template/ my-skill/
@@ -285,26 +344,32 @@ npm install
 ### 3. Testing
 ```bash
 # Compile your skill
-lua compile
+lua skill compile
 
 # Test your tools interactively
-lua test
+lua skill test
 ```
 
 ### 4. Deployment
 ```bash
-# Deploy to Lua platform
-lua deploy
+# Push version to server
+lua skill push
+
+# Deploy to production
+lua skill deploy
 ```
 
 ### 5. Iteration
 ```bash
 # Make changes to your tools
 # Recompile and test
-lua compile && lua test
+lua skill compile && lua skill test
+
+# Push updates
+lua skill push
 
 # Deploy updates
-lua deploy
+lua skill deploy
 ```
 
 ## Requirements
@@ -329,14 +394,130 @@ To contribute to this project:
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
+## User Data API
+
+The Lua CLI provides a built-in User Data API that allows your tools to interact with persistent user data stored in the Lua system.
+
+### Basic Usage
+
+```typescript
+import { user } from 'lua-cli';
+
+// Get user data
+const userData = await user.data.get();
+console.log('User data:', userData);
+
+// Create or update user data
+await user.data.create({
+  name: 'John Doe',
+  preferences: {
+    theme: 'dark',
+    language: 'en'
+  }
+});
+
+// Update existing data
+await user.data.update({
+  name: 'Jane Doe',
+  preferences: {
+    theme: 'light',
+    language: 'es'
+  }
+});
+
+// Clear all user data
+await user.data.clear();
+```
+
+### Using in Tools
+
+```typescript
+import { LuaTool } from 'lua-cli';
+import { user } from 'lua-cli';
+import { z } from 'zod';
+
+export class UserPreferencesTool extends LuaTool {
+  constructor() {
+    super('user-preferences', 'Manage user preferences');
+  }
+
+  async execute(input: { action: string; key?: string; value?: string }) {
+    const { action, key, value } = input;
+
+    switch (action) {
+      case 'get':
+        const userData = await user.data.get();
+        return { preferences: userData.preferences || {} };
+      
+      case 'set':
+        if (!key || !value) {
+          throw new Error('Key and value are required for set action');
+        }
+        
+        const currentData = await user.data.get();
+        const updatedData = {
+          ...currentData,
+          preferences: {
+            ...currentData.preferences,
+            [key]: value
+          }
+        };
+        
+        await user.data.update(updatedData);
+        return { success: true, message: `Set ${key} to ${value}` };
+      
+      case 'clear':
+        await user.data.clear();
+        return { success: true, message: 'All preferences cleared' };
+      
+      default:
+        throw new Error('Invalid action. Use: get, set, or clear');
+    }
+  }
+
+  getInputSchema() {
+    return z.object({
+      action: z.enum(['get', 'set', 'clear']).describe('Action to perform'),
+      key: z.string().optional().describe('Preference key (required for set action)'),
+      value: z.string().optional().describe('Preference value (required for set action)')
+    });
+  }
+}
+```
+
+### API Reference
+
+- `user.data.get()` - Retrieves current user data
+- `user.data.create(data)` - Creates or updates user data
+- `user.data.update(data)` - Updates existing user data (alias for create)
+- `user.data.clear()` - Clears all user data
+
+For more details, see [USER_DATA_API.md](./USER_DATA_API.md).
+
 ## Support
 
 For support and questions:
 - Create an issue on [GitHub](https://github.com/lua-ai-global/lua-cli/issues)
-- Contact: stefan@heylua.ai
+- Contact: stefan@lua.dev
 
 ## Changelog
 
+### 1.4.0
+- **Agent Creation**: Added ability to create new agents during `lua skill init`
+- **Agent Type Selection**: Choose from various agent types (Base Agent, Shopify, WooCommerce, etc.)
+- **Metadata Collection**: Automatic collection of required metadata for agent types
+- **Feature Configuration**: Enable/disable features like RAG, tickets, web search
+- **Persona Generation**: Automatic persona and welcome message generation for new agents
+- **Enhanced YAML**: Added persona and welcome message fields to configuration file
+
+### 1.3.0
+- **Command Restructure**: Reorganized commands under `lua auth` and `lua skill` groups
+- **New Push Command**: Added `lua skill push` to push versions to server
+- **New Deploy Command**: Added `lua skill deploy` to deploy versions to production
+- **Version Management**: Added version field to YAML configuration
+- **Improved UX**: Better command organization and intuitive naming
+- **Enhanced Workflow**: Complete skill lifecycle from init to production deployment
+
 ### 1.2.0
 - **Tool Development Framework**: Complete LuaSkill and LuaTool framework
 - **Dependency Bundling**: Automatic bundling of npm packages using esbuild

package/dist/commands/agents.js

@@ -1,20 +1,20 @@
-import fetch from "node-fetch";
+import { ApiService } from '../services/api.js';
 import { loadApiKey } from "../services/auth.js";
+import { withErrorHandling, writeSuccess } from "../utils/cli.js";
 export async function agentsCommand() {
-    const apiKey = await loadApiKey();
-    if (!apiKey) {
-        console.error("❌ No API key found. Run `lua configure` first.");
-        process.exit(1);
-    }
-    const response = await fetch("https://api.heylua.ai/admin", {
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-        },
-    });
-    if (!response.ok) {
-        console.error(`❌ Error ${response.status}: ${await response.text()}`);
-        process.exit(1);
-    }
-    const data = await response.json();
-    console.log("✅ Agents:", JSON.stringify(data, null, 2));
+    return withErrorHandling(async () => {
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            console.error("❌ No API key found. Run `lua configure` first.");
+            process.exit(1);
+        }
+        const response = await ApiService.Agent.getOrganizations(apiKey);
+        if (!response.success) {
+            console.error(`❌ Error: ${response.error?.message || 'Unknown error'}`);
+            process.exit(1);
+        }
+        const data = response.data;
+        writeSuccess("✅ Agents retrieved successfully:");
+        console.log(JSON.stringify(data, null, 2));
+    }, "agents listing");
 }

package/dist/commands/apiKey.js

@@ -1,24 +1,29 @@
 import inquirer from "inquirer";
 import { loadApiKey } from "../services/auth.js";
+import { withErrorHandling, clearPromptLines, writeProgress, writeSuccess } from "../utils/cli.js";
 export async function apiKeyCommand() {
-    const apiKey = await loadApiKey();
-    if (!apiKey) {
-        console.log("ℹ️  No API key found. Run `lua configure` first.");
-        return;
-    }
-    const { confirm } = await inquirer.prompt([
-        {
-            type: "confirm",
-            name: "confirm",
-            message: "This will display your API key. Are you sure you want to continue?",
-            default: false
+    return withErrorHandling(async () => {
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            writeProgress("ℹ️  No API key found. Run `lua configure` first.");
+            return;
         }
-    ]);
-    if (confirm) {
-        console.log("🔑 Your API key:");
-        console.log(apiKey);
-    }
-    else {
-        console.log("ℹ️  API key display cancelled.");
-    }
+        const { confirm } = await inquirer.prompt([
+            {
+                type: "confirm",
+                name: "confirm",
+                message: "This will display your API key. Are you sure you want to continue?",
+                default: false
+            }
+        ]);
+        // Clear the confirmation prompt lines
+        clearPromptLines(2);
+        if (confirm) {
+            writeSuccess("🔑 Your API key:");
+            console.log(apiKey);
+        }
+        else {
+            writeProgress("ℹ️  API key display cancelled.");
+        }
+    }, "key display");
 }

package/dist/commands/compile.d.ts

@@ -0,0 +1 @@
+export declare function compileCommand(): Promise<void>;