lua-cli 3.0.0-alpha.1 → 3.0.0-alpha.5

package/README.md

@@ -1,865 +0,0 @@
-# Lua CLI
-
-Build AI agents with custom capabilities using TypeScript.
-
-[![npm version](https://img.shields.io/npm/v/lua-cli.svg)](https://www.npmjs.com/package/lua-cli)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
----
-
-## 🎯 What is Lua CLI?
-
-Lua CLI is a powerful command-line tool for building, testing, and deploying AI skills. A **skill** is a collection of **tools** (functions) that your AI agent can use to accomplish tasks.
-
-**Think of it like:**
-- 🤖 **AI Agent** = Your assistant (like ChatGPT)
-- 🎯 **Skills** = What it can do (your custom capabilities)
-- 🛠️ **Tools** = Specific functions (e.g., "get weather", "create order")
-
----
-
-## ⚡ Quick Start
-
-```bash
-# Install
-npm install -g lua-cli
-
-# Authenticate
-lua auth configure
-
-# Create a project
-mkdir my-skill && cd my-skill
-lua init
-
-# Test locally
-lua test
-
-# Start dev mode
-lua dev
-```
-
-**Done!** Your AI skill is running at http://localhost:3000 🎉
-
----
-
-## 📦 Installation
-
-### Global Installation (Recommended)
-
-```bash
-npm install -g lua-cli
-```
-
-### Using npx (No Installation)
-
-```bash
-npx lua-cli [command]
-```
-
-### Requirements
-
-- **Node.js** 16.0.0 or higher
-- **npm** 7.0.0 or higher
-- **TypeScript** knowledge (for development)
-
----
-
-## 🚀 Features
-
-### For Developers
-- 🔨 **TypeScript-first** - Full type safety and autocomplete
-- 🎨 **Template System** - 30+ example tools to learn from
-- 🧪 **Interactive Testing** - Test tools before deployment
-- 🔄 **Live Reload** - Dev mode with automatic recompilation
-- 📦 **Auto Bundling** - Dependencies bundled automatically with esbuild
-- ✅ **Input Validation** - Zod schema validation built-in
-
-### For Operations
-- 🔐 **Secure Auth** - API key or email OTP authentication
-- 🌐 **Multi-Skill** - Multiple skills in one project
-- 📊 **Version Management** - Push, test, and deploy versions
-- 🎯 **Sandbox Testing** - Test in isolation before production
-- 📝 **Environment Variables** - Secure configuration management
-
-### For Users
-- 💬 **Chat Interface** - Test your AI in real conversations
-- 🔍 **Tool Explorer** - Browse and test individual tools
-- 📊 **Real-time Logs** - WebSocket log streaming
-- 🎨 **Beautiful UI** - Modern, intuitive interface
-
----
-
-## 📖 Documentation
-
-### 📘 **For Beginners**
-**[Getting Started Guide](GETTING_STARTED.md)** - Zero to deployed skill in one hour
-- Installation and setup
-- Your first skill
-- Step-by-step tutorial
-- Complete restaurant skill example
-
-### 🔧 **For Developers**
-**[API Reference](API_REFERENCE.md)** - Complete API documentation
-- All exported APIs (User, Data, Products, Baskets, Orders)
-- Type definitions
-- Code examples
-- Best practices
-
-**[Template Guide](TEMPLATE_GUIDE.md)** - Understanding the example project
-- Template structure explained
-- 30+ tool examples
-- Building your first skill
-- Common patterns and recipes
-
-### 💻 **For CLI Users**
-**[CLI Reference](CLI_REFERENCE.md)** - All command documentation
-- Complete command reference
-- Flags and options
-- Workflow examples
-- Troubleshooting
-
-### 🏗️ **For Contributors**
-**[Developer Guide](DEVELOPER_GUIDE.md)** - Architecture and internals
-- Codebase structure
-- Module organization
-- Contributing guidelines
-
----
-
-## 🎓 Core Concepts
-
-### Skills
-
-A skill is a collection of related tools:
-
-```typescript
-import { LuaSkill } from 'lua-cli';
-
-const weatherSkill = new LuaSkill({
-  name: "weather-skill",
-  version: "1.0.0",
-  description: "Provides weather information",
-  context: "Use get_weather when users ask about weather...",
-  tools: [
-    new GetWeatherTool(),
-    new GetForecastTool()
-  ]
-});
-```
-
-### Tools
-
-A tool is a single function the AI can call:
-
-```typescript
-import { LuaTool } from 'lua-cli';
-import { z } from 'zod';
-
-export default class GetWeatherTool implements LuaTool {
-  name = "get_weather";
-  description = "Get current weather for a city";
-  
-  inputSchema = z.object({
-    city: z.string()
-  });
-
-  async execute(input: any) {
-    // Call weather API
-    return {
-      temperature: 72,
-      condition: "sunny",
-      city: input.city
-    };
-  }
-}
-```
-
-### Platform APIs
-
-Built-in APIs for common operations:
-
-```typescript
-import { User, Data, Products, Baskets, Orders } from 'lua-cli';
-
-// User data
-const user = await User.get();
-
-// Custom data with vector search
-await Data.create('movies', movieData, searchText);
-const results = await Data.search('movies', 'sci-fi thriller');
-
-// Products
-const products = await Products.search('laptop');
-
-// Shopping baskets
-const basket = await Baskets.create({ currency: 'USD' });
-await Baskets.addItem(basketId, { id, price, quantity });
-
-// Orders
-const order = await Baskets.placeOrder(orderData, basketId);
-```
-
----
-
-## 💡 Examples
-
-### Example 1: Simple Weather Tool
-
-```typescript
-import { LuaTool } from 'lua-cli';
-import { z } from 'zod';
-
-export default class WeatherTool implements LuaTool {
-  name = "get_weather";
-  description = "Get weather for any city";
-  inputSchema = z.object({ city: z.string() });
-
-  async execute(input: any) {
-    const response = await fetch(
-      `https://api.open-meteo.com/v1/forecast?city=${input.city}`
-    );
-    const data = await response.json();
-    return { temperature: data.temp, condition: data.condition };
-  }
-}
-```
-
-### Example 2: E-commerce Tool
-
-```typescript
-import { LuaTool, Products, Baskets } from 'lua-cli';
-import { z } from 'zod';
-
-export default class AddToCartTool implements LuaTool {
-  name = "add_to_cart";
-  description = "Add product to shopping cart";
-  
-  inputSchema = z.object({
-    productId: z.string(),
-    quantity: z.number().min(1)
-  });
-
-  async execute(input: any) {
-    const product = await Products.getById(input.productId);
-    const basket = await Baskets.create({ currency: 'USD' });
-    
-    await Baskets.addItem(basket.id, {
-      id: input.productId,
-      price: product.price,
-      quantity: input.quantity
-    });
-    
-    return {
-      basketId: basket.id,
-      message: `Added ${input.quantity}x ${product.name} to cart`
-    };
-  }
-}
-```
-
-### Example 3: Custom Data with Search
-
-```typescript
-import { LuaTool, Data } from 'lua-cli';
-import { z } from 'zod';
-
-export class CreateMovieTool implements LuaTool {
-  name = "create_movie";
-  description = "Add a movie to the database";
-  
-  inputSchema = z.object({
-    title: z.string(),
-    director: z.string(),
-    year: z.number()
-  });
-
-  async execute(input: any) {
-    const searchText = `${input.title} ${input.director} ${input.year}`;
-    const movie = await Data.create('movies', input, searchText);
-    return { id: movie.id, message: 'Movie added' };
-  }
-}
-
-export class SearchMoviesTool implements LuaTool {
-  name = "search_movies";
-  description = "Search movies by title, director, or year";
-  inputSchema = z.object({ query: z.string() });
-
-  async execute(input: any) {
-    const results = await Data.search('movies', input.query, 10, 0.7);
-    return { movies: results.data, count: results.count };
-  }
-}
-```
-
----
-
-## 🎯 Commands
-
-### Authentication
-```bash
-lua auth configure    # Set up API key
-lua auth key          # Display API key
-lua auth logout       # Delete API key
-```
-
-### Skill Management
-```bash
-lua init              # Create new skill project
-lua compile           # Compile TypeScript to deployable format
-lua test              # Test tools interactively
-lua push              # Upload version to server
-lua deploy            # Deploy version to production
-lua dev               # Development mode with live reload
-```
-
-### Utilities
-```bash
-lua admin             # Open Lua Admin Dashboard in browser
-lua docs              # Open documentation in browser
-```
-
-**See [CLI_REFERENCE.md](CLI_REFERENCE.md) for complete command documentation.**
-
----
-
-## 🛠️ Development Workflow
-
-### Local Development
-
-```bash
-# Start dev mode
-lua dev
-
-# Make changes to src/tools/*.ts
-# Save → Auto-recompiles → Auto-pushes to sandbox
-# Test in browser at http://localhost:3000
-```
-
-### Testing
-
-```bash
-# Test individual tools
-lua test
-
-# Test conversationally
-lua dev
-# Use chat interface
-```
-
-### Deployment
-
-```bash
-# Upload new version
-lua push
-
-# Deploy to production
-lua deploy
-```
-
----
-
-## 📚 Built-in APIs
-
-### User API
-```typescript
-import { User } from 'lua-cli';
-
-const user = await User.get();
-```
-
-### Custom Data API (with Vector Search)
-```typescript
-import { Data } from 'lua-cli';
-
-await Data.create('collection', data, searchText);
-const results = await Data.search('collection', 'query', limit, threshold);
-```
-
-### Products API
-```typescript
-import { Products } from 'lua-cli';
-
-const products = await Products.search('laptop');
-await Products.create({ name, price });
-```
-
-### Baskets API
-```typescript
-import { Baskets, BasketStatus } from 'lua-cli';
-
-const basket = await Baskets.create({ currency: 'USD' });
-await Baskets.addItem(basketId, { id, price, quantity });
-```
-
-### Orders API
-```typescript
-import { Orders, OrderStatus } from 'lua-cli';
-
-const order = await Baskets.placeOrder(orderData, basketId);
-await Orders.updateStatus(OrderStatus.FULFILLED, orderId);
-```
-
-**See [API_REFERENCE.md](API_REFERENCE.md) for complete API documentation.**
-
----
-
-## 🎨 Template Project
-
-The template includes 30+ working examples:
-
-- 🌤️ **Weather Tool** - External API integration
-- 👤 **User Data Tools** - User management
-- 🛍️ **Product Tools** - E-commerce catalog
-- 🛒 **Basket Tools** - Shopping cart
-- 📦 **Order Tools** - Order processing
-- 🎬 **Custom Data Tools** - Vector search
-- 💳 **Payment Tool** - Payment integration
-
-**See [TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md) for complete template documentation.**
-
----
-
-## 🔒 Security
-
-- ✅ API keys stored in system keychain
-- ✅ Environment variables for secrets
-- ✅ Secure VM sandbox for tool execution
-- ✅ No hardcoded credentials
-- ✅ HTTPS for all API calls
-
-**Best Practices:**
-```typescript
-import { env } from 'lua-cli';
-
-// ✅ Good - Use environment variables
-const apiKey = env('EXTERNAL_API_KEY');
-
-// ❌ Bad - Hardcoded secrets
-const apiKey = 'sk_abc123';
-```
-
----
-
-## 🧪 Testing
-
-### Unit Testing
-
-```typescript
-import { describe, it, expect } from '@jest/globals';
-import MyTool from './tools/MyTool';
-
-describe('MyTool', () => {
-  it('should return expected result', async () => {
-    const tool = new MyTool();
-    const result = await tool.execute({ input: 'test' });
-    expect(result).toHaveProperty('success');
-  });
-});
-```
-
-### Interactive Testing
-
-```bash
-lua test
-# Select tool → Enter inputs → See results
-```
-
-### Conversational Testing
-
-```bash
-lua dev
-# Chat with AI at http://localhost:3000
-```
-
----
-
-## 🎯 Use Cases
-
-### Customer Service
-- Answer FAQs from knowledge base
-- Look up order status
-- Create support tickets
-- Search documentation
-
-### E-commerce
-- Product search and recommendations
-- Shopping cart management
-- Order creation and tracking
-- Inventory checks
-
-### Booking & Scheduling
-- Check availability
-- Create appointments
-- Send confirmations
-- Manage reservations
-
-### Data Management
-- CRUD operations on custom data
-- Vector search for semantic queries
-- Data aggregation and reporting
-- Integration with external systems
-
----
-
-## 📊 Architecture
-
-```
-┌─────────────────┐
-│   AI Agent      │
-│   (Lua Platform)│
-└────────┬────────┘
-         │
-         ↓
-┌─────────────────┐
-│   Your Skills   │ ← Built with Lua CLI
-│   (TypeScript)  │
-└────────┬────────┘
-         │
-         ↓
-┌─────────────────┐
-│   Your Tools    │
-│   (Functions)   │
-└────────┬────────┘
-         │
-         ↓
-┌─────────────────┐
-│  Platform APIs  │ ← User, Products, Data, etc.
-│  External APIs  │ ← Weather, Stripe, SendGrid, etc.
-│  Databases      │ ← Your own systems
-└─────────────────┘
-```
-
----
-
-## 🌟 Key Features
-
-### Type-Safe Development
-```typescript
-// Full TypeScript support
-import { LuaTool, Products } from 'lua-cli';
-import { z } from 'zod';
-
-// Autocomplete, type checking, and validation
-export default class MyTool implements LuaTool {
-  inputSchema = z.object({
-    query: z.string()  // Validated at runtime
-  });
-  
-  async execute(input: z.infer<typeof this.inputSchema>) {
-    // input is fully typed!
-    return await Products.search(input.query);
-  }
-}
-```
-
-### Instant Feedback
-```bash
-lua dev
-# Edit file → Save → Auto-reload → Test immediately
-```
-
-### Production Ready
-```bash
-lua push    # Upload to server
-lua deploy  # Deploy to all users
-```
-
----
-
-## 📖 Learning Resources
-
-### 🟢 **New to Lua?**
-Start here: **[GETTING_STARTED.md](GETTING_STARTED.md)**
-- Installation
-- First skill in 1 hour
-- Complete tutorial
-- Common patterns
-
-### 🟡 **Building Skills?**
-Read: **[API_REFERENCE.md](API_REFERENCE.md)**
-- All exported APIs
-- Type definitions
-- Code examples
-- Best practices
-
-### 🟠 **Understanding Examples?**
-Read: **[TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md)**
-- Template structure
-- 30+ tool examples
-- Common recipes
-- Migration guide
-
-### 🔵 **Using the CLI?**
-Read: **[CLI_REFERENCE.md](CLI_REFERENCE.md)**
-- All commands
-- Flags and options
-- Workflows
-- Troubleshooting
-
-### 🟣 **Contributing?**
-Read: **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)**
-- Architecture
-- Module structure
-- Contribution guidelines
-
----
-
-## 🔧 Common Tasks
-
-### Create a New Tool
-
-```bash
-# Create file
-touch src/tools/MyTool.ts
-```
-
-```typescript
-import { LuaTool } from 'lua-cli';
-import { z } from 'zod';
-
-export default class MyTool implements LuaTool {
-  name = "my_tool";
-  description = "What it does";
-  inputSchema = z.object({ param: z.string() });
-
-  async execute(input: any) {
-    // Your logic here
-    return { success: true };
-  }
-}
-```
-
-Add to skill in `src/index.ts`:
-```typescript
-import MyTool from './tools/MyTool';
-
-const skill = new LuaSkill({
-  tools: [new MyTool()]
-});
-```
-
----
-
-### Call External APIs
-
-```typescript
-import { LuaTool, env } from 'lua-cli';
-
-export default class ExternalApiTool implements LuaTool {
-  async execute(input: any) {
-    const apiKey = env('EXTERNAL_API_KEY');
-    
-    const response = await fetch('https://api.example.com/data', {
-      headers: { 'Authorization': `Bearer ${apiKey}` }
-    });
-    
-    return await response.json();
-  }
-}
-```
-
----
-
-### Use Platform APIs
-
-```typescript
-import { LuaTool, Products, Baskets } from 'lua-cli';
-
-export default class ShoppingTool implements LuaTool {
-  async execute(input: any) {
-    // Search products
-    const products = await Products.search(input.query);
-    
-    // Create basket
-    const basket = await Baskets.create({ currency: 'USD' });
-    
-    // Add item
-    await Baskets.addItem(basket.id, {
-      id: products.data[0].id,
-      price: products.data[0].price,
-      quantity: 1
-    });
-    
-    return { basketId: basket.id };
-  }
-}
-```
-
----
-
-### Store Custom Data
-
-```typescript
-import { LuaTool, Data } from 'lua-cli';
-
-export default class SaveNoteTool implements LuaTool {
-  async execute(input: any) {
-    // Create
-    const note = await Data.create('notes', {
-      title: input.title,
-      content: input.content,
-      tags: input.tags
-    }, `${input.title} ${input.content}`);
-    
-    // Search later
-    const results = await Data.search('notes', 'meeting notes', 10);
-    
-    return { noteId: note.id };
-  }
-}
-```
-
----
-
-## 🎯 Example Projects
-
-### Knowledge Base Assistant
-```typescript
-Tools: search_kb, create_article, update_article
-APIs: Data (vector search)
-Use Case: Company documentation, FAQ
-```
-
-### E-commerce Bot
-```typescript
-Tools: search_products, add_to_cart, checkout
-APIs: Products, Baskets, Orders
-Use Case: Online shopping assistant
-```
-
-### Booking System
-```typescript
-Tools: check_availability, make_reservation, cancel_booking
-APIs: Data (custom collections)
-Use Case: Restaurant/hotel reservations
-```
-
-### CRM Assistant
-```typescript
-Tools: find_customer, create_lead, update_contact
-APIs: Data, User
-Use Case: Customer relationship management
-```
-
----
-
-## 🚀 Deployment
-
-### Development → Production Flow
-
-```bash
-# 1. Develop locally
-lua dev
-# Edit, test, iterate
-
-# 2. Push to server
-lua push
-
-# 3. Test in sandbox
-lua dev
-# Final testing
-
-# 4. Deploy to production
-lua deploy
-# Available to all users!
-```
-
-### Version Management
-
-Update version in `lua.skill.yaml`:
-```yaml
-skills:
-  - name: my-skill
-    version: 1.0.1  # ← Increment this
-```
-
-Then push and deploy:
-```bash
-lua push    # Uploads v1.0.1
-lua deploy  # Deploys v1.0.1
-```
-
----
-
-## ⚙️ Configuration
-
-### Environment Variables
-
-**`.env` file:**
-```bash
-STRIPE_API_KEY=sk_test_abc123
-SENDGRID_KEY=SG.xyz789
-CUSTOM_API_URL=https://api.example.com
-```
-
-**`lua.skill.yaml`:**
-```yaml
-skill:
-  env:
-    PRODUCTION_API_KEY: sk_live_abc123
-    BASE_URL: https://prod.example.com
-```
-
-**Access in code:**
-```typescript
-import { env } from 'lua-cli';
-
-const key = env('STRIPE_API_KEY');
-```
-
----
-
-## 🤝 Contributing
-
-We welcome contributions!
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Write tests
-5. Submit a pull request
-
-See [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for architecture details.
-
----
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
----
-
-## 🔗 Links
-
-- **Documentation**: https://docs.heylua.ai
-- **Platform**: https://heylua.ai
-- **GitHub**: https://github.com/lua-ai/lua-cli
-- **npm**: https://www.npmjs.com/package/lua-cli
-
----
-
-## 💬 Support
-
-- **Issues**: [GitHub Issues](https://github.com/lua-ai/lua-cli/issues)
-- **Email**: support@lua.ai
-- **Docs**: https://docs.heylua.ai
-
----
-
-## 🎉 Quick Links
-
-| I want to... | Read this... |
-|--------------|--------------|
-| **Get started** | [GETTING_STARTED.md](GETTING_STARTED.md) |
-| **Learn the API** | [API_REFERENCE.md](API_REFERENCE.md) |
-| **Use CLI commands** | [CLI_REFERENCE.md](CLI_REFERENCE.md) |
-| **Understand examples** | [TEMPLATE_GUIDE.md](TEMPLATE_GUIDE.md) |
-| **Contribute code** | [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) |
-| **See changelog** | [CHANGELOG.md](CHANGELOG.md) |
-
----
-
-**Happy building! 🚀**
-
-Made with ❤️ by the Lua team