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

package/CLI_REFERENCE.md

@@ -1,908 +0,0 @@
-# Lua CLI - Command Reference
-
-Complete reference guide for all Lua CLI commands.
-
----
-
-## 📋 Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Authentication Commands](#authentication-commands)
-- [Skill Management Commands](#skill-management-commands)
-- [Command Reference](#command-reference)
-
----
-
-## Installation
-
-```bash
-npm install -g lua-cli
-```
-
-Or use with npx (no installation required):
-```bash
-npx lua-cli [command]
-```
-
----
-
-## Quick Start
-
-```bash
-# 1. Authenticate
-lua auth configure
-
-# 2. Initialize a new skill project
-mkdir my-skill && cd my-skill
-lua init
-
-# 3. Test your skill locally
-lua test
-
-# 4. Push to development environment
-lua push
-
-# 5. Start development mode with live reload
-lua dev
-
-# 6. Deploy to production
-lua deploy
-```
-
----
-
-## Authentication Commands
-
-### `lua auth configure`
-
-Sets up your Lua CLI authentication credentials.
-
-**Usage:**
-```bash
-lua auth configure
-```
-
-**Interactive Prompts:**
-1. Choose authentication method:
-   - **API Key**: Enter an existing API key
-   - **Email**: Get API key via email OTP
-
-**For API Key Method:**
-- Prompts for your API key
-- Validates the key with the server
-- Stores securely in system keychain
-
-**For Email Method:**
-- Prompts for email address
-- Sends 6-digit OTP code to your email
-- Allows 3 attempts to enter correct OTP
-- Automatically generates and saves API key
-
-**Storage:**
-- Credentials stored in system keychain
-- macOS: Keychain
-- Windows: Credential Vault
-- Linux: libsecret
-
-**Example:**
-```bash
-$ lua auth configure
-? Choose authentication method: Email
-? Enter your email address: you@example.com
-📧 Sending OTP to your email...
-✅ OTP sent successfully!
-? Enter the OTP code: 123456
-🔐 Verifying OTP...
-✅ OTP verified successfully!
-🔑 Generating API key...
-✅ API key generated and saved securely.
-```
-
----
-
-### `lua auth key`
-
-Displays your stored API key.
-
-**Usage:**
-```bash
-lua auth key
-```
-
-**Interactive Prompts:**
-- Confirmation prompt before displaying (security)
-
-**Output:**
-```bash
-$ lua auth key
-? This will display your API key. Are you sure you want to continue? Yes
-🔑 Your API key:
-lsk_abc123def456...
-```
-
-**Security Note:** Only displays after explicit confirmation to prevent accidental exposure.
-
----
-
-### `lua auth logout`
-
-Deletes your stored API key from the system.
-
-**Usage:**
-```bash
-lua auth logout
-```
-
-**Interactive Prompts:**
-- Confirmation prompt (action cannot be undone)
-
-**What it does:**
-- Removes API key from system keychain
-- Does NOT invalidate the key on the server
-- You'll need to run `lua auth configure` again to use the CLI
-
-**Example:**
-```bash
-$ lua auth logout
-? Are you sure you want to delete your API key? This action cannot be undone. Yes
-✅ API key deleted successfully.
-```
-
----
-
-## Skill Management Commands
-
-### `lua init`
-
-Initializes a new Lua skill project in the current directory.
-
-**Usage:**
-```bash
-mkdir my-skill && cd my-skill
-lua init
-```
-
-**Interactive Prompts:**
-
-**Step 1: Choose Agent**
-- **Select existing agent**: Choose from your organizations and agents
-- **Create new agent**: Create a new AI agent
-
-**Step 2a: For Existing Agent**
-- Select organization
-- Select agent from organization
-
-**Step 2b: For New Agent**
-- Enter business name (default: "Private")
-- Enter agent name (required)
-- Select business type from list
-- Select brand personality
-- Enter brand traits (optional)
-- Configure features (enable/disable)
-
-**What it creates:**
-```
-my-skill/
-├── src/
-│   ├── index.ts              # Skill entry point
-│   ├── tools/                # Tool implementations
-│   │   ├── GetWeatherTool.ts
-│   │   ├── UserDataTool.ts
-│   │   ├── ProductsTool.ts
-│   │   └── ... (more examples)
-│   └── services/             # Helper services
-├── lua.skill.yaml            # Skill configuration
-├── package.json              # Dependencies
-├── tsconfig.json             # TypeScript config
-├── .env.example              # Environment variables template
-└── README.md                 # Project documentation
-```
-
-**Configuration File (`lua.skill.yaml`):**
-```yaml
-agent:
-  agentId: agent_abc123
-  orgId: org_xyz789
-  persona: "..."
-  welcomeMessage: "..."
-
-skills: []  # Auto-populated during compilation
-```
-
-**Example:**
-```bash
-$ lua init
-? What would you like to do? Create new agent
-? Enter business name: My Coffee Shop
-? Enter agent name: CoffeeBot
-? Select business type: Food & Beverage (e.g. restaurant, bakery)
-? Select brand personality: Friendly
-? Enter brand traits: Warm, welcoming, knowledgeable about coffee
-🔄 Creating agent...
-✅ Agent created successfully!
-⏳ Waiting for agent to be ready...
-✅ Created lua.skill.yaml
-✅ Copied template files
-📦 Installing dependencies...
-✅ Lua skill project initialized successfully!
-```
-
----
-
-### `lua compile`
-
-Compiles your TypeScript skill into deployable JavaScript bundles.
-
-**Usage:**
-```bash
-lua compile
-```
-
-**What it does:**
-1. Analyzes your TypeScript code to detect tools
-2. Bundles each tool individually with esbuild
-3. Bundles the main index file
-4. Extracts tool metadata and schemas
-5. Creates deployment artifacts
-6. Automatically creates skills via API if needed
-
-**Output:**
-```
-dist/
-├── deployment.json           # Deployment metadata
-├── index.js                  # Main skill bundle
-└── tools/                    # Individual tool bundles
-    ├── GetWeatherTool.js
-    ├── UserDataTool.js
-    └── ...
-
-.lua/
-├── deploy.json               # Legacy format
-├── get_weather.js            # Uncompressed (for debugging)
-└── ...
-```
-
-**Example:**
-```bash
-$ lua compile
-🔨 Compiling Lua skill...
-📦 Found 15 tools to bundle...
-📦 Bundling GetWeatherTool...
-📦 Bundling UserDataTool...
-... (more tools)
-📦 Bundling main index...
-✅ Skill compiled successfully - 15 tools bundled
-```
-
-**Notes:**
-- Automatically detects tools from `new LuaSkill({ tools: [...] })`
-- Automatically detects tools from `skill.addTools([...])`
-- Creates skills in `lua.skill.yaml` if they don't exist
-- Updates existing skills with new tools
-
----
-
-### `lua test`
-
-Tests individual tools locally in a sandboxed environment.
-
-**Usage:**
-```bash
-lua test
-```
-
-**Interactive Prompts:**
-1. Select a tool from the list
-2. Enter input values based on the tool's schema
-3. View execution results
-
-**What it does:**
-1. Compiles the skill
-2. Lists all available tools
-3. Prompts for tool selection
-4. Dynamically generates input prompts based on tool's input schema
-5. Executes tool in secure VM sandbox
-6. Displays results or errors
-
-**Features:**
-- Supports nested object inputs
-- Validates required vs optional fields
-- Loads environment variables from `.env` and `lua.skill.yaml`
-- Secure sandbox execution (isolated from host system)
-- Detailed error reporting
-
-**Example:**
-```bash
-$ lua test
-🧪 Testing Lua skill...
-📦 Compiling code first...
-✅ Skill compiled successfully
-📄 Loaded environment variables from .env file
-
-? 🔧 Select a tool to test:
-❯ get_weather - Get the weather for a given city
-  create_product - Create a new product
-  get_user_data - Get user data
-  
-✅ Selected tool: get_weather
-
-📝 Enter input values:
-? city (required): London
-
-🚀 Executing tool...
-Input: {
-  "city": "London"
-}
-✅ Tool execution successful!
-Output: {
-  "weather": "3",
-  "city": "London",
-  "temperature": 15.2,
-  "description": "Windspeed 12.3 km/h"
-}
-```
-
----
-
-### `lua push`
-
-Pushes your compiled skill version to the Lua server.
-
-**Usage:**
-```bash
-lua push
-```
-
-**Interactive Prompts:**
-- Confirmation to push version
-
-**What it does:**
-1. Reads version from `lua.skill.yaml`
-2. Prompts for confirmation
-3. Authenticates with API key
-4. Compiles the skill
-5. Validates deploy.json matches config
-6. Uploads version to server
-
-**Requirements:**
-- Must be in a skill directory (has `lua.skill.yaml`)
-- Must have run `lua init`
-- Must have valid API key
-
-**Example:**
-```bash
-$ lua push
-? Are you sure you want to push version 1.0.0? Yes
-✅ Authenticated
-🔄 Compiling skill...
-✅ Skill compiled successfully - 10 tools bundled
-🔄 Pushing version to server...
-✅ Version 1.0.0 pushed successfully
-```
-
-**Note:** This uploads to the server but does NOT deploy to production. Use `lua deploy` for production deployment.
-
----
-
-### `lua deploy`
-
-Deploys a specific version to production (all users).
-
-**Usage:**
-```bash
-lua deploy
-```
-
-**Interactive Prompts:**
-1. Select version to deploy from list
-2. Confirm deployment with warning
-
-**What it does:**
-1. Fetches all available versions from server
-2. Displays versions with metadata:
-   - Version number
-   - Current status (if currently deployed)
-   - Created date
-   - Creator email
-3. Prompts for version selection
-4. Shows warning about production deployment
-5. Publishes selected version
-
-**Features:**
-- Lists all pushed versions
-- Shows which version is currently active
-- Sorts by date (newest first)
-- Requires explicit confirmation
-
-**Example:**
-```bash
-$ lua deploy
-✅ Authenticated
-🔄 Fetching available versions...
-
-? Select a version to deploy:
-  1.0.2 - Created: Oct 3, 2025 by you@example.com
-  1.0.1 - Created: Oct 2, 2025 by you@example.com
-❯ 1.0.0 (CURRENT) - Created: Oct 1, 2025 by you@example.com
-
-? ⚠️  Warning: This version will be deployed to all users. Do you want to proceed? Yes
-🔄 Publishing version...
-✅ Version 1.0.0 deployed successfully
-```
-
-**⚠️ WARNING:** This immediately deploys to ALL users. Test thoroughly with `lua dev` first!
-
----
-
-### `lua dev`
-
-Starts development mode with live reloading and chat interface.
-
-**Usage:**
-```bash
-lua dev
-```
-
-**What it does:**
-1. Compiles the skill
-2. Pushes all skills to sandbox environment
-3. Starts local web server on port 3000
-4. Opens chat interface in your browser
-5. Watches for file changes
-6. Auto-recompiles and pushes on changes
-
-**Features:**
-- **Live Chat Interface**: Test your skill with conversational AI
-- **Tool Testing**: Test individual tools with custom inputs
-- **WebSocket Logging**: Real-time log streaming
-- **Auto-Reload**: Automatic recompilation on file changes
-- **Environment Management**: Edit `.env` variables in UI
-- **Persona Configuration**: Customize agent behavior
-- **Multi-Skill Support**: Works with multiple skills in one project
-
-**Chat Interface Features:**
-```
-http://localhost:3000
-
-Tabs:
-├── Chat        # Chat with your AI agent using sandbox skills
-├── Tools       # Test individual tools with custom inputs
-├── User Data   # View and modify user data
-├── Environment # Manage environment variables
-├── Persona     # Configure agent personality
-└── Skills      # View all skills and their tools
-```
-
-**File Watching:**
-- Watches: `.ts` files in `src/`
-- Ignores: `node_modules/`, `dist/`, `.lua/`, `.git/`
-- Debounce: 500ms (prevents multiple compilations)
-
-**Example:**
-```bash
-$ lua dev
-✅ Authenticated
-🔄 Compiling skill...
-✅ Skill compiled successfully - 10 tools bundled
-🔄 Pushing skills to sandbox...
-✅ Pushed 3 skills to sandbox
-🌐 Chat interface opened in your browser
-🔍 Watching for file changes... (Press Ctrl+C to stop)
-
-# Edit a file...
-🔄 File changed: src/tools/MyTool.ts - Compiling and pushing...
-✅ Compilation completed
-✅ Successfully pushed 3 skills to sandbox
-```
-
-**Stopping Dev Mode:**
-Press `Ctrl+C` to stop the file watcher and server.
-
----
-
-### `lua admin`
-
-Opens the Lua Admin Dashboard in your default browser.
-
-**Usage:**
-```bash
-lua admin
-```
-
-**What it does:**
-1. Loads your API key from secure storage
-2. Reads your skill configuration (agentId and orgId)
-3. Constructs authenticated admin dashboard URL
-4. Opens the dashboard in your default browser
-
-**Requirements:**
-- Must be authenticated (`lua auth configure`)
-- Must be in a skill directory (has `lua.skill.yaml`)
-- Config must contain `agent.agentId` and `agent.orgId`
-
-**What You Can Do:**
-- **📊 Usage Analytics** - View API calls, skill usage, performance
-- **⚙️ Agent Configuration** - Manage settings, persona, metadata
-- **💳 Billing & Subscriptions** - View plans, payment, billing history
-- **👥 Team Management** - Add/remove members, permissions
-- **🔑 API Key Management** - View, generate, revoke keys
-
-**Example:**
-```bash
-$ lua admin
-✓ Lua Admin Dashboard opened in your browser
-
-  Dashboard URL: https://admin.heylua.ai
-  Agent ID: agent-abc123
-  Organization ID: org-xyz789
-```
-
-**Errors:**
-```bash
-# No API key
-❌ Error during admin: No API key found. Please run "lua configure" first.
-
-# Not in skill directory
-❌ Error during admin: Could not read lua.skill.yaml. Please ensure you are in a Lua skill directory.
-
-# Missing configuration
-❌ Error during admin: No agentId found in lua.skill.yaml. Please ensure your configuration is valid.
-```
-
----
-
-### `lua docs`
-
-Opens the Lua documentation website in your default browser.
-
-**Usage:**
-```bash
-lua docs
-```
-
-**What it does:**
-Opens https://docs.heylua.ai in your default browser for quick access to:
-- Platform overview and concepts
-- CLI command reference
-- API documentation and guides
-- Tool examples (30+ examples)
-- Integration tutorials
-- Best practices and tips
-
-**Requirements:**
-None - works from anywhere
-
-**Example:**
-```bash
-$ lua docs
-✓ Lua Documentation opened in your browser
-
-  Documentation: https://docs.heylua.ai
-```
-
-**Documentation Sections:**
-- **Overview** - Platform introduction and key concepts
-- **CLI** - Complete command reference
-- **API Reference** - Platform APIs (Products, Baskets, Orders, Data)
-- **Tool Examples** - E-commerce, integrations, custom logic
-- **Demos** - Full example implementations
-- **Best Practices** - Tips for building effective agents
-
----
-
-## Command Reference
-
-### Global Flags
-
-All commands support:
-- `--help` - Show command help
-- `--version` - Show CLI version
-
-### Error Handling
-
-All commands include:
-- Descriptive error messages
-- Exit codes (0 = success, 1 = error)
-- Helpful troubleshooting hints
-
-### Common Errors
-
-**"No API key found"**
-```bash
-❌ No API key found. Run `lua auth configure` first.
-```
-**Solution:** Run `lua auth configure` to set up authentication.
-
-**"No lua.skill.yaml found"**
-```bash
-❌ No lua.skill.yaml found. Please run this command from a skill directory.
-```
-**Solution:** Run command from a skill directory or run `lua init` first.
-
-**"Missing agentId or skillId"**
-```bash
-❌ Missing agentId or skillId in skill configuration
-```
-**Solution:** Run `lua init` to set up your skill properly.
-
----
-
-## Workflow Examples
-
-### **Complete Workflow: New Project**
-
-```bash
-# 1. Set up authentication
-lua auth configure
-
-# 2. Create new project
-mkdir my-weather-skill
-cd my-weather-skill
-lua init
-
-# 3. Customize your tools (edit src/tools/*.ts)
-# 4. Test locally
-lua test
-
-# 5. Push to server
-lua push
-
-# 6. Start development mode
-lua dev
-# Test in chat interface at http://localhost:3000
-
-# 7. When ready, deploy to production
-lua deploy
-```
-
----
-
-### **Development Workflow**
-
-```bash
-# Start dev mode
-lua dev
-
-# Edit files - auto-reloads
-# Test in chat interface
-# When satisfied, push new version
-
-# Stop dev mode (Ctrl+C)
-
-# Push production version
-lua push
-
-# Deploy to all users
-lua deploy
-```
-
----
-
-### **Testing Workflow**
-
-```bash
-# Test individual tools
-lua test
-# Select tool, enter inputs, see results
-
-# Test in conversational context
-lua dev
-# Use chat interface to test natural language interaction
-```
-
----
-
-## Environment Variables
-
-### Loading Priority
-
-Environment variables are loaded in this order (later overrides earlier):
-
-1. System environment (`process.env`)
-2. `.env` file in project root
-3. `lua.skill.yaml` under `skill.env`
-
-### Using in Tools
-
-```typescript
-import { env } from 'lua-cli';
-
-export class MyTool implements LuaTool {
-  async execute(input: any) {
-    const apiKey = env('EXTERNAL_API_KEY');
-    const baseUrl = env('API_BASE_URL') || 'https://default.com';
-    
-    // Use environment variables...
-  }
-}
-```
-
-### Setting Variables
-
-**Option 1: `.env` file**
-```bash
-# .env
-EXTERNAL_API_KEY=your_key_here
-API_BASE_URL=https://api.example.com
-```
-
-**Option 2: `lua.skill.yaml`**
-```yaml
-skill:
-  name: my-skill
-  version: 1.0.0
-  env:
-    EXTERNAL_API_KEY: your_key_here
-    API_BASE_URL: https://api.example.com
-```
-
-**Option 3: Dev Mode UI**
-- Go to http://localhost:3000 during `lua dev`
-- Click "Environment" tab
-- Edit variables in UI
-- Changes saved to `.env` file
-
----
-
-## Configuration File
-
-### `lua.skill.yaml`
-
-Created by `lua init`, updated by compilation.
-
-**Structure:**
-```yaml
-# Agent Configuration
-agent:
-  agentId: agent_abc123        # Your agent ID
-  orgId: org_xyz789            # Organization ID
-  persona: "..."               # Agent personality (optional)
-  welcomeMessage: "..."        # Welcome message (optional)
-
-# Legacy single skill format (deprecated)
-skill:
-  name: my-skill
-  version: 1.0.0
-  skillId: skill_legacy123
-
-# New multi-skill format (recommended)
-skills:
-  - name: general-skill
-    version: 1.0.0
-    skillId: skill_abc123
-  - name: product-skill
-    version: 1.0.0
-    skillId: skill_def456
-
-# Environment Variables (optional)
-skill:
-  env:
-    API_KEY: your_key_here
-    BASE_URL: https://api.example.com
-```
-
-**Auto-managed Fields:**
-- `skillId` - Automatically created during compilation
-- `skills` array - Auto-populated from your code
-
-**Manual Fields:**
-- `agentId` - Set during `lua init`
-- `orgId` - Set during `lua init`
-- `version` - Update manually when releasing new versions
-- `env` - Set your environment variables here
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-**Skill not found during dev**
-```bash
-💡 The skill doesn't exist on the server.
-   Please run "lua push" first to deploy your skill, then try "lua dev" again.
-```
-**Solution:** Run `lua push` before `lua dev`.
-
-**Compilation fails**
-```bash
-❌ No index.ts found in current directory or src/ directory
-```
-**Solution:** Create `index.ts` or `src/index.ts` with your skill definition.
-
-**Version mismatch**
-```bash
-❌ Version mismatch: config has 1.0.1, deploy.json has 1.0.0
-```
-**Solution:** Recompile after changing version in `lua.skill.yaml`.
-
-### Getting Help
-
-- Check command help: `lua [command] --help`
-- Visit documentation: https://docs.heylua.ai
-- View examples in template: Check `template/` directory after install
-
----
-
-## Best Practices
-
-### Versioning
-- Use semantic versioning: `MAJOR.MINOR.PATCH`
-- Increment PATCH for bug fixes
-- Increment MINOR for new features
-- Increment MAJOR for breaking changes
-
-### Development
-- Always test with `lua test` before pushing
-- Use `lua dev` for iterative development
-- Test thoroughly before deploying to production
-- Keep `.env` file in `.gitignore`
-
-### Deployment
-- Push new versions frequently for testing
-- Only deploy stable versions to production
-- Document changes between versions
-- Test in sandbox (dev mode) before deploying
-
----
-
-## Advanced Usage
-
-### Multiple Skills in One Project
-
-You can define multiple skills in `index.ts`:
-
-```typescript
-const skill1 = new LuaSkill({
-  name: 'general-skill',
-  description: '...',
-  context: '...',
-  tools: [tool1, tool2]
-});
-
-const skill2 = new LuaSkill({
-  name: 'ecommerce-skill',
-  description: '...',
-  context: '...',
-  tools: [tool3, tool4]
-});
-```
-
-The CLI automatically:
-- Detects all skills
-- Creates separate skill IDs
-- Bundles all tools
-- Manages multi-skill deployments
-
-### Custom Build Configuration
-
-Modify `tsconfig.json` for TypeScript settings.
-
-The CLI uses:
-- **esbuild** for fast bundling
-- **ts-morph** for AST analysis
-- **VM sandboxing** for secure execution
-
----
-
-## Command Summary
-
-| Command | Purpose | Requires |
-|---------|---------|----------|
-| `lua auth configure` | Set up API key | Nothing |
-| `lua auth key` | Show API key | API key |
-| `lua auth logout` | Delete API key | API key |
-| `lua init` | Initialize project | API key |
-| `lua compile` | Compile skill | Skill directory |
-| `lua test` | Test tools | Compiled skill |
-| `lua push` | Upload version | Compiled skill, API key |
-| `lua deploy` | Deploy to prod | Pushed versions |
-| `lua dev` | Dev mode | Compiled skill, pushed version |
-
----
-
-**For detailed API documentation, see `API_REFERENCE.md`**  
-**For template documentation, see `TEMPLATE_GUIDE.md`**  
-**For development guide, see `DEVELOPER_GUIDE.md`**
-