@ludeo/cli 1.0.0 → 1.1.0

package/README.md

@@ -1,17 +1,42 @@
 # Ludeo CLI
 
-A command-line tool for studios to upload game builds and manage content on the Ludeo platform.
+A comprehensive command-line tool for studios to upload game builds and manage content on the Ludeo platform with complete file upload capabilities.
 
-## Features
+## 🚀 Features
 
 - **Complete Build Uploads**: Upload both build metadata and all build files in one command
 - **Multipart File Uploads**: Automatically handles large files (>100MB) using multipart uploads
-- **Concurrent Uploads**: Uploads multiple files simultaneously for faster processing
-- **Progress Tracking**: Real-time progress updates during file uploads
-- **Authentication**: Secure access token-based authentication
-- **Environment Support**: Staging and production environment support
+- **Concurrent Uploads**: Uploads multiple files simultaneously with 32 workers for maximum performance
+- **Upload Recovery**: Automatic retry logic with exponential backoff and state persistence
+- **Progress Tracking**: Real-time progress updates during file uploads with worker statistics
+- **Dynamic Service Selection**: Automatically chooses between local and API services
+- **Secure Authentication**: Access token-based authentication with automatic validation
+- **Environment Support**: Staging, production, and development environment support
+- **Session Management**: Automatic token validation and session refresh
 
-## Quick Start
+## 🏗️ Architecture
+
+The CLI uses a dynamic service architecture that automatically adapts based on your authentication status:
+
+- **Authenticated Mode**: Full API service with complete file uploads via cloud-builds
+- **Local Mode**: Metadata-only service for development and testing
+- **Automatic Fallback**: Seamlessly switches between services as needed
+
+## 📦 Installation
+
+### Build from Source
+```bash
+git clone <repository>
+cd ludeo-cli
+make build
+```
+
+### Install Locally
+```bash
+make install
+```
+
+## 🚀 Quick Start
 
 ### Option 1: NPM Installation (Recommended for most users)
 ```bash
@@ -39,13 +64,12 @@ make build
 ### 3. Upload a Complete Build
 ```bash
 ./build/ludeo builds upload \
-  --game-version-id YOUR_GAME_VERSION_ID \
-  --base-path ./builds \
+  --game-id YOUR_GAME_ID \
   --exec-path ./builds/game.exe \
   --local-directory ./builds
 ```
 
-## Usage
+## 📚 Usage
 
 ### Authentication Commands
 ```bash
@@ -68,18 +92,18 @@ ludeo auth logout
 ludeo builds upload [flags]
 
 # List builds for a game version
-ludeo builds list --game-version-id <id>
+ludeo builds list --game-id <id>
 
 # Get build details
-ludeo builds get --game-version-id <id> --build-id <id>
+ludeo builds get --game-id <id> --build-id <id>
 ```
 
-#### Upload Required Flags
-- `--game-version-id`: Game version ID
-- `--exec-path`: Path to the executable (full path)
-- `--local-directory`: Local directory containing all build files
+### Upload Required Flags
+- `--game-id`: Game ID (required)
+- `--exec-path`: Path to the executable relative to local directory (required)
+- `--local-directory`: Local directory containing all build files (required)
 
-#### Upload Optional Flags
+### Upload Optional Flags
 - `--game-version`: Game version (e.g., 1.2.3)
 - `--sdk-version`: SDK version (e.g., 2.0.0)
 - `--runtime-environment`: Runtime environment (e.g., windows, linux)
@@ -88,15 +112,15 @@ ludeo builds get --game-version-id <id> --build-id <id>
 - `--major-build-id`: Major build ID for minor builds
 - `--request-id`: Request ID for tracking
 
-## Authentication Flow
+## 🔐 Authentication Flow
 
 The CLI implements a secure authentication flow that validates access tokens before any upload operation:
 
 1. **Token Storage**: Access tokens are stored securely in `~/.ludeo/config.json`
 2. **Pre-upload Validation**: Every upload operation automatically validates the token first
-3. **API Endpoint**: Calls `{{baseUrl}}/v3/authentication/cli/:accessToken` to validate tokens
-4. **Session Management**: Creates/validates session for the token if it doesn't exist
-5. **Secure Uploads**: All subsequent uploads use the validated token
+3. **API Endpoint**: Calls `{{baseUrl}}/authentication/cli` with Authorization header
+4. **Session Management**: Receives session token from authentication endpoint
+5. **Secure Uploads**: All subsequent uploads use the session token as Bearer token
 
 ### Security Features
 - **Automatic Validation**: Tokens are validated before every API operation
@@ -104,34 +128,7 @@ The CLI implements a secure authentication flow that validates access tokens bef
 - **Secure Storage**: Tokens are stored in user's home directory with appropriate permissions
 - **No Token Logging**: Only first/last 4 characters of tokens are displayed in logs
 
-## Examples
-
-### Basic Complete Upload
-```bash
-ludeo builds upload \
-  --game-version-id 123 \
-  --exec-path ./builds/game.exe \
-  --local-directory ./builds
-```
-
-### Upload with Optional Parameters
-```bash
-ludeo builds upload \
-  --game-version-id 123 \
-  --exec-path ./builds/game.exe \
-  --local-directory ./builds \
-  --game-version "1.2.3" \
-  --sdk-version "2.1.0" \
-  --changes-description "Bug fixes and performance improvements" \
-  --runtime-environment "windows"
-```
-
-### List Builds
-```bash
-ludeo builds list --game-version-id 123
-```
-
-## How It Works
+## 🔧 How It Works
 
 ### Complete Upload Process
 The CLI performs a complete upload in the following steps:
@@ -147,6 +144,12 @@ The CLI performs a complete upload in the following steps:
 5. **File Registration**: Registers uploaded files with the cloud-builds service
 6. **Completion**: Marks the upload as complete
 
+### Dynamic Service Selection
+The CLI automatically chooses the appropriate service based on your authentication status:
+
+- **With Access Token**: Uses complete API service with file uploads
+- **Without Token**: Falls back to local service (metadata only)
+
 ### Base Path Derivation
 The CLI automatically derives the `basePath` from your `--local-directory`:
 
@@ -169,18 +172,20 @@ This matches exactly how the UI works - the system derives the base path from th
 
 ### File Upload Features
 - **Automatic Multipart**: Files over 100MB automatically use multipart uploads
-- **Concurrent Processing**: Up to 4 files uploaded simultaneously
-- **Progress Tracking**: Real-time progress updates for large uploads
-- **Error Handling**: Automatic retry and failure marking
+- **Concurrent Processing**: Up to 32 files uploaded simultaneously for maximum performance
+- **Upload Recovery**: Automatic retry with exponential backoff and state persistence
+- **Progress Tracking**: Real-time progress updates with worker statistics
+- **Error Handling**: Graceful error handling without stopping other uploads
 - **Cross-Platform**: Handles Windows and Unix path separators
 
 ### Performance
-- **Concurrent Uploads**: Multiple files uploaded simultaneously
+- **High-Performance Concurrent Uploads**: 32 workers for maximum throughput
 - **Multipart Optimization**: Large files split into 100MB parts for optimal performance
 - **Connection Reuse**: HTTP connections reused for better performance
-- **Progress Reporting**: Real-time feedback during long uploads
+- **Progress Reporting**: Real-time feedback with detailed worker statistics
+- **Upload State Persistence**: Recovery from interruptions in `~/.ludeo-upload-state/`
 
-## Configuration
+## ⚙️ Configuration
 
 The CLI stores configuration in `~/.ludeo/config.json`. You can also use environment variables:
 
@@ -189,16 +194,74 @@ The CLI stores configuration in `~/.ludeo/config.json`. You can also use environ
 - `LUDEO_API_BASE_URL`: Sonic-server API base URL
 - `LUDEO_CLOUD_BUILDS_URL`: Cloud-builds API base URL
 
-### Default Configuration
+### Environment Support
+
+The CLI supports three environments:
+
+#### Staging (Default)
 ```json
 {
   "environment": "staging",
-  "api_base_url": "https://services.stg.use1.ludeo.com/api/v3/sonic-server",
+  "api_base_url": "https://services.stg.use1.ludeo.com/api/v3",
   "cloud_builds_url": "https://services.stg.use1.ludeo.com/api/v3/cloud-builds"
 }
 ```
 
-## Development
+#### Production
+```json
+{
+  "environment": "production",
+  "api_base_url": "https://services.ludeo.com/api/v3",
+  "cloud_builds_url": "https://services.ludeo.com/api/v3/cloud-builds"
+}
+```
+
+#### Development (Internal Use Only)
+```json
+{
+  "environment": "development",
+  "api_base_url": "http://localhost:80/api/v3",
+  "cloud_builds_url": "http://localhost:80/api/v3/cloud-builds"
+}
+```
+
+### Environment Variables
+You can set the environment using environment variables:
+- `LUDEO_ENVIRONMENT`: Set to "development", "staging", or "production"
+
+## 📋 Examples
+
+### Basic Complete Upload
+```bash
+ludeo builds upload \
+  --game-id 123 \
+  --exec-path ./builds/game.exe \
+  --local-directory ./builds
+```
+
+### Upload with Optional Parameters
+```bash
+ludeo builds upload \
+  --game-id 123 \
+  --exec-path ./builds/game.exe \
+  --local-directory ./builds \
+  --game-version "1.2.3" \
+  --sdk-version "2.1.0" \
+  --changes-description "Bug fixes and performance improvements" \
+  --runtime-environment "windows"
+```
+
+### List Builds
+```bash
+ludeo builds list --game-id 123
+```
+
+### Get Build Details
+```bash
+ludeo builds get --game-id 123 --build-id 456
+```
+
+## 🛠️ Development
 
 ### Building
 ```bash
@@ -212,10 +275,19 @@ make test
 
 ### Local Development
 ```bash
+# For local development, use environment variables (recommended)
+export LUDEO_ENVIRONMENT=development
+./ludeo auth login --access-token YOUR_TOKEN
+
+# Note: --env flag is hidden from users and only available for internal development
+```
+
+### Go Development
+```bash
 go run main.go builds upload --help
 ```
 
-## Troubleshooting
+## 🚨 Troubleshooting
 
 ### Common Issues
 
@@ -232,11 +304,17 @@ go run main.go builds upload --help
    - Multipart uploads require stable network connections
    - Very large files (>1GB) may take significant time
    - Monitor progress output for upload status
+   - Upload state is automatically saved for recovery
 
 4. **Path Issues**
    - Use forward slashes (/) in paths for cross-platform compatibility
    - Ensure executable path is relative to base path
 
+5. **Service Selection Issues**
+   - Check authentication status with `ludeo auth status`
+   - Verify access token is properly stored
+   - Check environment configuration
+
 ### Debug Mode
 Enable debug output by setting the log level:
 ```bash
@@ -244,9 +322,34 @@ export LUDEO_LOG_LEVEL=debug
 ludeo builds upload [flags]
 ```
 
-## Support
+### Service Mode Debugging
+The CLI provides detailed logging about which service is being used:
+- **API Service**: Full functionality with file uploads and concurrent processing
+- **Local Service**: Metadata only, no file uploads
+
+### Concurrent Upload Debugging
+- **Upload State**: Check `~/.ludeo-upload-state/` for recovery files
+- **Worker Statistics**: Monitor progress output for active worker counts
+- **Retry Logic**: Failed uploads automatically retry with exponential backoff
+
+## 📖 API Reference
+
+### Service Interfaces
+- **`builds.Service`**: Basic build operations (metadata only)
+- **`builds.CompleteUploadService`**: Complete upload operations including files
+
+### Key Endpoints
+- **Authentication**: `{{baseUrl}}/authentication/cli`
+- **Builds**: `{{baseUrl}}/sonic-server/builds`
+- **Cloud Builds**: `{{cloudBuildsUrl}}/uploads`
+
+## 🤝 Support
 
 For issues and questions:
 - Check the troubleshooting section above
 - Review the CLI output for error details
 - Contact the Ludeo platform team
+
+## 📄 License
+
+This project is proprietary to Ludeo and its partners.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ludeo/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Ludeo CLI - Upload game builds and manage content on the Ludeo platform",
   "main": "index.js",
   "bin": {
-    "ludeo": "./bin/ludeo.js"
+    "ludeo": "bin/ludeo.js"
   },
   "scripts": {
     "build": "make build-all",
@@ -23,7 +23,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ludeo/cli.git"
+    "url": "git+https://github.com/ludeo/cli.git"
   },
   "engines": {
     "node": ">=16.0.0"
@@ -44,4 +44,3 @@
     "arm64"
   ]
 }
-