lemonade-interactive-loader 1.0.0

package/README.md

@@ -0,0 +1,288 @@
+# 🍋 Lemonade Launcher
+
+[![License: ISC](https://img.shields.io/badge/Lxicense-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](#)
+
+**The easiest way to manage llama.cpp builds and run Lemonade Server**
+
+Lemonade Launcher is a professional, cross-platform CLI tool that simplifies downloading llama.cpp builds and launching Lemonade Server with an intuitive interactive interface.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+git clone https://github.com/yourusername/lemonade-launcher.git
+cd lemonade-launcher
+npm install
+```
+
+### Running the Tool
+
+```bash
+# Start the interactive CLI
+npm start
+# or
+node index.js
+```
+
+That's it! You'll be presented with a friendly menu to configure and run your server.
+
+## 🎯 What You Can Do
+
+### Interactive Menu Options
+
+The main menu adapts based on whether you have a configuration saved:
+
+**When NO configuration exists:**
+```
+? What would you like to do?
+❯ 🚀 Setup - Configure Lemonade Server
+  📦 Download Custom llama.cpp Builds
+```
+
+**When configuration EXISTS:**
+```
+? What would you like to do?
+❯ ▶️  Start Server with Current Config
+  ✏️  Edit Configuration
+  👁️  View Configuration
+  🔄 Reset Configuration
+  ──────────────────────────────────────
+  🚀 Setup - Configure Lemonade Server
+  📦 Download Custom llama.cpp Builds
+```
+
+| Command | Description |
+|---------|-------------||
+| **▶️ Start Server** | Launch Lemonade Server with saved config (when config exists) |
+| **✏️ Edit Configuration** | Update your saved settings interactively |
+| **👁️ View Configuration** | See your current configuration and installed builds |
+| **🔄 Reset Configuration** | Start fresh by resetting all settings |
+| **🚀 Setup** | Run the 8-question setup wizard to configure everything |
+| **📦 Download Builds** | View, delete, or download custom llama.cpp builds |
+
+### The Setup Wizard
+
+Just answer 8 simple questions:
+
+1. **Network access?** Should the server be accessible from other devices?
+2. **Port number?** Which port should it run on? (default: 8080)
+3. **Logging level?** Choose from info, debug, warning, or error
+4. **Model directory?** Point to existing models (like LM Studio) if needed
+5. **Interface type?** System tray or headless mode
+6. **Custom arguments?** Any additional llama.cpp parameters?
+7. **Custom build?** Use a specific llama.cpp build from GitHub?
+8. **Backend?** Choose auto, vulkan, rocm, or cpu
+
+## ✨ Key Features
+
+- **🎨 User-Friendly Interface** - Interactive menus, no command-line expertise needed
+- **💾 Smart Configuration** - Save settings once, use them forever
+- **📦 Build Management** - Browse, download, and manage multiple llama.cpp builds
+- **🖥️ Backend Flexibility** - Support for CPU, CUDA, ROCm, Vulkan, and more
+- **🌐 Network Ready** - Easily configure localhost or network access
+- **🔄 Cross-Platform** - Works seamlessly on Windows, Linux, and macOS
+- **🎯 Auto-Detection** - Automatically suggests the best builds for your system
+- **⚡ Quick Launch** - Start your server with a single command
+
+## 📖 Documentation
+
+- **📚 [Usage Guide](#-quick-start)** - Get started quickly
+- **🔧 [Technical Documentation](TECHNICAL_README.md)** - Deep dive into architecture and API
+- **🛠️ [Troubleshooting](#-troubleshooting)** - Common issues and solutions
+
+## 🎬 Usage Examples
+
+### First-Time Setup
+
+```bash
+$ node index.js
+
+╔════════════════════════════════════════════════════════╗
+║            🍋 Lemonade Interactive Launcher            ║
+╚════════════════════════════════════════════════════════╝
+
+⚠️  No configuration found. Please run Setup first.
+
+? What would you like to do?
+❯ 🚀 Setup - Configure Lemonade Server
+  📦 Download Custom llama.cpp Builds
+```
+
+### After Configuration
+
+```bash
+$ node index.js
+
+╔════════════════════════════════════════════════════════╗
+║            🍋 Lemonade Interactive Launcher            ║
+╚════════════════════════════════════════════════════════╝
+
+? What would you like to do?
+❯ ▶️  Start Server with Current Config
+  ✏️  Edit Configuration
+  👁️  View Configuration
+  🔄 Reset Configuration
+  ──────────────────────────────────────
+  🚀 Setup - Configure Lemonade Server
+  📦 Download Custom llama.cpp Builds
+```
+
+### Downloading a Custom Build
+
+1. Select **📦 Download Custom llama.cpp Builds**
+2. Choose **⬇️ Download new build**
+3. Pick a release from the list
+4. Select the asset for your platform
+5. Sit back while it downloads and extracts automatically
+
+### Running with Custom Models
+
+Point Lemonade Server to your existing model directory (like LM Studio's):
+
+```
+? Is there another model directory to use? (example: LM Studio) Yes
+? Enter the model directory path: /home/user/.local/share/lmstudio/models
+```
+
+## 🛠️ Configuration
+
+Configuration is automatically saved and loaded:
+
+- **Location**: `~/.lemonade-launcher/config.json` (Linux/macOS) or `%USERPROFILE%\.lemonade-launcher\config.json` (Windows)
+- **Format**: JSON
+- **Auto-saved**: After every setup or edit
+
+### Example Configuration
+
+```json
+{
+  "exposeToNetwork": false,
+  "host": "127.0.0.1",
+  "port": 8080,
+  "logLevel": "info",
+  "backend": "auto",
+  "modelDir": "None",
+  "runMode": "headless",
+  "llamacppArgs": "",
+  "customLlamacppPath": ""
+}
+```
+
+## 🌍 Cross-Platform Support
+
+### Supported Systems
+
+| Platform | Versions | Architecture |
+|----------|----------|--------------|
+| **Windows** | 10, 11 | x64, arm64 |
+| **Linux** | Ubuntu, Debian, CentOS, etc. | x64, arm64, armv7l |
+| **macOS** | 10.15+ (Catalina+) | x64, arm64 (Apple Silicon) |
+
+### Automatic Platform Detection
+
+Lemonade Launcher automatically:
+- Detects your operating system and architecture
+- Suggests the best matching llama.cpp builds
+- Uses the correct file paths and command syntax
+- Handles platform-specific quirks
+
+## 📦 Programmatic Usage
+
+Use Lemonade Launcher as a library in your own projects:
+
+```javascript
+const { 
+  fetchAllReleases,
+  downloadAndExtractLlamaCpp,
+  loadConfig,
+  saveConfig
+} = require('./src/index');
+
+// Fetch available releases
+const releases = await fetchAllReleases(10);
+
+// Download a specific build
+await downloadAndExtractLlamaCpp(asset, version);
+
+// Manage configuration
+const config = loadConfig();
+config.port = 9090;
+saveConfig(config);
+```
+
+See the [Technical Documentation](TECHNICAL_README.md) for the full API reference.
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### "Command not found" or "npm: command not found"
+**Solution**: Ensure Node.js and npm are installed and in your PATH.
+
+#### Permission denied errors (Linux/macOS)
+```bash
+chmod +x index.js
+```
+
+#### Permission denied errors (Windows)
+Run Command Prompt or PowerShell as Administrator.
+
+#### Build download fails
+- Check your internet connection
+- Ensure you have write permissions to `~/.lemonade-launcher/`
+- Try downloading the asset manually from GitHub
+
+#### Server won't start
+- Verify lemonade-server is installed: [lemonade-server.ai](https://lemonade-server.ai)
+- Check that the configuration is correct: `node index.js` → View Configuration
+- Try running with debug logging: Set log level to "debug" in setup
+
+### Getting Help
+
+1. Check the [Technical Documentation](TECHNICAL_README.md)
+2. Review the [Troubleshooting Guide](TECHNICAL_README.md#troubleshooting)
+3. Open an issue on GitHub
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Make** your changes
+4. **Test** thoroughly on your platform
+5. **Commit** your changes (`git commit -m 'Add amazing feature'`)
+6. **Push** to the branch (`git push origin feature/amazing-feature`)
+7. **Open** a Pull Request
+
+### Code of Conduct
+
+- Be respectful and inclusive
+- Follow the existing code style
+- Write clear commit messages
+- Document your changes
+
+## 📚 Resources
+
+- [Technical Documentation](TECHNICAL_README.md) - Architecture, API reference, and development guide
+- [llama.cpp](https://github.com/ggml-org/llama.cpp) - The underlying inference engine
+- [Lemonade Server](https://lemonade-server.ai) - The server being launched
+
+## 📄 License
+
+This project is licensed under the ISC License. See the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [llama.cpp](https://github.com/ggml-org/llama.cpp) team for the amazing inference engine
+- [Lemonade Server](https://lemonade-server.ai) for the server implementation
+- The Node.js community for the fantastic ecosystem
+
+---
+
+**Made with 🍋 by Nxtmind**
+
+*Happy prompting!*

package/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/**
+ * Lemonade Launcher - Main Entry Point
+ * 
+ * This file serves as the primary entry point for the CLI tool.
+ * All functionality has been refactored into modular components under src/
+ */
+
+const { runCLI } = require('./src/index');
+
+// Run the CLI
+runCLI().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "lemonade-interactive-loader",
+  "version": "1.0.0",
+  "description": "Interactive CLI tool to launch Lemonade Server with custom arguments and download llama.cpp releases - Cross-platform (Windows/Linux)",
+  "main": "index.js",
+  "bin": {
+    "lemonade-interactive-loader": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "llama.cpp",
+    "lemonade",
+    "llm",
+    "cli",
+    "cross-platform",
+    "windows",
+    "linux"
+  ],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "os": [
+    "win32",
+    "linux",
+    "darwin"
+  ],
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "inquirer": "^8.2.6",
+    "tar": "^7.5.9",
+    "unzipper": "^0.12.3"
+  }
+}

package/src/README.md

@@ -0,0 +1,88 @@
+# Lemonade Launcher - Source Code Structure
+
+> **Note:** For comprehensive technical documentation, API references, and development guides, please see the main [TECHNICAL_README.md](../TECHNICAL_README.md) in the project root.
+
+This directory contains the modular source code for the Lemonade Launcher CLI tool.
+
+## Directory Structure
+
+```
+src/
+├── index.js              # Main entry point and module exports
+├── config/               # Configuration management
+│   ├── index.js          # Config load/save/reset functions
+│   └── constants.js      # Application constants and defaults
+├── services/             # Business logic services
+│   ├── github.js         # GitHub API interactions
+│   ├── download.js       # File download and extraction
+│   ├── asset-manager.js  # Installed asset management
+│   └── server.js         # Server launch and management
+├── utils/                # Utility functions
+│   └── system.js         # System detection and formatting
+└── cli/                  # Command-line interface
+    ├── menu.js           # Main menu and command handling
+    ├── prompts.js        # Interactive prompts and selections
+    └── setup-wizard.js   # Configuration setup wizard
+```
+
+## Module Overview
+
+### Config (`config/`)
+- **constants.js**: Centralized configuration for paths, defaults, and constants
+- **index.js**: Configuration persistence (load, save, reset)
+
+### Services (`services/`)
+- **github.js**: Fetch releases from llama.cpp GitHub repository
+- **download.js**: Download files and extract archives (zip/tar.gz)
+- **asset-manager.js**: Manage installed llama.cpp builds
+- **server.js**: Launch lemonade-server with configuration
+
+### Utils (`utils/`)
+- **system.js**: System detection, byte formatting, asset categorization
+
+### CLI (`cli/`)
+- **menu.js**: Main menu system and command routing
+- **prompts.js**: Interactive prompts for release/asset selection
+- **setup-wizard.js**: 8-question setup wizard
+
+## Architecture Principles
+
+1. **Separation of Concerns**: Each module has a single responsibility
+2. **Dependency Injection**: Modules depend on abstractions, not concretions
+3. **Cross-Platform**: All code works on Windows, Linux, and macOS
+4. **Error Handling**: Proper error handling with informative messages
+5. **Modularity**: Easy to test, maintain, and extend
+
+## Usage
+
+### As CLI Tool
+```bash
+node index.js
+```
+
+### As Module
+```javascript
+const { 
+  loadConfig, 
+  fetchAllReleases, 
+  downloadAndExtractLlamaCpp,
+  launchLemonadeServer 
+} = require('./src/index');
+
+// Use exported functions programmatically
+```
+
+## Adding New Features
+
+1. Create new module in appropriate directory
+2. Export functions from `src/index.js`
+3. Update documentation
+4. Add tests (when test framework is added)
+
+## Code Style
+
+- Use ES6+ syntax
+- Async/await for asynchronous operations
+- JSDoc comments for public APIs
+- Consistent error handling patterns
+- Modular and reusable code