@ludeo/cli 1.0.0

package/README.md

@@ -0,0 +1,252 @@
+# Ludeo CLI
+
+A command-line tool for studios to upload game builds and manage content on the Ludeo platform.
+
+## 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
+
+## Quick Start
+
+### Option 1: NPM Installation (Recommended for most users)
+```bash
+# Install globally
+npm install -g @ludeo/cli
+
+# Verify installation
+ludeo --version
+
+# Authenticate
+ludeo auth login --access-token YOUR_ACCESS_TOKEN
+```
+
+### Option 2: Build from Source
+#### 1. Build the CLI
+```bash
+make build
+```
+
+#### 2. Authenticate
+```bash
+./build/ludeo auth login --access-token YOUR_ACCESS_TOKEN
+```
+
+### 3. Upload a Complete Build
+```bash
+./build/ludeo builds upload \
+  --game-version-id YOUR_GAME_VERSION_ID \
+  --base-path ./builds \
+  --exec-path ./builds/game.exe \
+  --local-directory ./builds
+```
+
+## Usage
+
+### Authentication Commands
+```bash
+# Login with access token
+ludeo auth login --access-token <token>
+
+# Check authentication status
+ludeo auth status
+
+# Validate current access token
+ludeo auth validate
+
+# Logout and clear credentials
+ludeo auth logout
+```
+
+### Builds Commands
+```bash
+# Upload a complete build (metadata + files)
+ludeo builds upload [flags]
+
+# List builds for a game version
+ludeo builds list --game-version-id <id>
+
+# Get build details
+ludeo builds get --game-version-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 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)
+- `--changes-description`: Description of changes in this build
+- `--base-build-id`: Base build ID for modification builds
+- `--major-build-id`: Major build ID for minor builds
+- `--request-id`: Request ID for tracking
+
+## 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
+
+### Security Features
+- **Automatic Validation**: Tokens are validated before every API operation
+- **Session Persistence**: Valid sessions are maintained for the duration of the token
+- **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
+
+### Complete Upload Process
+The CLI performs a complete upload in the following steps:
+
+1. **Validation**: Validates the local directory and build parameters
+2. **Base Path Derivation**: Automatically derives `basePath` from the root folder name of `--local-directory`
+   - Example: `--local-directory ./builds` → `basePath = "builds"`
+   - Example: `--local-directory ./game-assets` → `basePath = "game-assets"`
+3. **Build Creation**: Creates build metadata via the sonic-server API with the derived `basePath`
+4. **File Upload**: Uploads all files to S3 via the cloud-builds service
+   - Small files (<100MB): Direct upload
+   - Large files (≥100MB): Multipart upload with concurrent parts
+5. **File Registration**: Registers uploaded files with the cloud-builds service
+6. **Completion**: Marks the upload as complete
+
+### Base Path Derivation
+The CLI automatically derives the `basePath` from your `--local-directory`:
+
+```bash
+# If you specify:
+--local-directory ./builds
+
+# The CLI will derive:
+basePath = "builds"
+
+# And send to the API:
+{
+  "basePath": "builds",
+  "execPath": "./builds/game.exe",  # Your input unchanged
+  "localDirectory": "./builds"      # Your input unchanged
+}
+```
+
+This matches exactly how the UI works - the system derives the base path from the uploaded directory structure.
+
+### 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
+- **Cross-Platform**: Handles Windows and Unix path separators
+
+### Performance
+- **Concurrent Uploads**: Multiple files uploaded simultaneously
+- **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
+
+## Configuration
+
+The CLI stores configuration in `~/.ludeo/config.json`. You can also use environment variables:
+
+- `LUDEO_ACCESS_TOKEN`: Your Ludeo access token
+- `LUDEO_ENVIRONMENT`: Target environment (staging, production)
+- `LUDEO_API_BASE_URL`: Sonic-server API base URL
+- `LUDEO_CLOUD_BUILDS_URL`: Cloud-builds API base URL
+
+### Default Configuration
+```json
+{
+  "environment": "staging",
+  "api_base_url": "https://services.stg.use1.ludeo.com/api/v3/sonic-server",
+  "cloud_builds_url": "https://services.stg.use1.ludeo.com/api/v3/cloud-builds"
+}
+```
+
+## Development
+
+### Building
+```bash
+make build
+```
+
+### Testing
+```bash
+make test
+```
+
+### Local Development
+```bash
+go run main.go builds upload --help
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication Errors**
+   - Ensure access token is valid and not expired
+   - Check that the access token has upload permissions
+
+2. **File Upload Failures**
+   - Verify local directory exists and is readable
+   - Check network connectivity to S3 endpoints
+   - Ensure files are not corrupted or locked
+
+3. **Large File Issues**
+   - Multipart uploads require stable network connections
+   - Very large files (>1GB) may take significant time
+   - Monitor progress output for upload status
+
+4. **Path Issues**
+   - Use forward slashes (/) in paths for cross-platform compatibility
+   - Ensure executable path is relative to base path
+
+### Debug Mode
+Enable debug output by setting the log level:
+```bash
+export LUDEO_LOG_LEVEL=debug
+ludeo builds upload [flags]
+```
+
+## Support
+
+For issues and questions:
+- Check the troubleshooting section above
+- Review the CLI output for error details
+- Contact the Ludeo platform team

package/bin/ludeo.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+
+// Determine the correct binary path based on platform and architecture
+function getBinaryPath() {
+  const platform = os.platform();
+  const arch = os.arch();
+  
+  // Map Node.js arch to Go arch
+  const archMap = {
+    'x64': 'amd64',
+    'arm64': 'arm64'
+  };
+  
+  const goArch = archMap[arch] || arch;
+  
+  // Map platform names
+  const platformMap = {
+    'win32': 'windows',
+    'darwin': 'darwin',
+    'linux': 'linux'
+  };
+  
+  const goPlatform = platformMap[platform] || platform;
+  
+  // Construct binary name
+  const binaryName = platform === 'win32' 
+    ? `ludeo-${goPlatform}-${goArch}.exe`
+    : `ludeo-${goPlatform}-${goArch}`;
+  
+  // Look for binary in dist/ directory (created by postinstall)
+  const distPath = path.join(__dirname, '..', 'dist', binaryName);
+  
+  if (fs.existsSync(distPath)) {
+    return distPath;
+  }
+  
+  // Fallback to build/ directory for development
+  const buildPath = path.join(__dirname, '..', 'build', binaryName);
+  
+  if (fs.existsSync(buildPath)) {
+    return buildPath;
+  }
+  
+  throw new Error(`Binary not found for ${platform}-${arch}. Expected: ${binaryName}`);
+}
+
+// Execute the Go binary with all arguments
+function main() {
+  try {
+    const binaryPath = getBinaryPath();
+    const args = process.argv.slice(2);
+    
+    // Spawn the Go binary with all arguments
+    const child = spawn(binaryPath, args, {
+      stdio: 'inherit',
+      cwd: process.cwd()
+    });
+    
+    child.on('error', (error) => {
+      console.error(`Failed to start Ludeo CLI: ${error.message}`);
+      process.exit(1);
+    });
+    
+    child.on('exit', (code) => {
+      process.exit(code);
+    });
+    
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    console.error('');
+    console.error('This usually means the CLI binary for your platform is missing.');
+    console.error('Try running: npm rebuild @ludeo/cli');
+    process.exit(1);
+  }
+}
+
+main();
+

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@ludeo/cli",
+  "version": "1.0.0",
+  "description": "Ludeo CLI - Upload game builds and manage content on the Ludeo platform",
+  "main": "index.js",
+  "bin": {
+    "ludeo": "./bin/ludeo.js"
+  },
+  "scripts": {
+    "build": "make build-all",
+    "postinstall": "node scripts/postinstall.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ludeo",
+    "cli",
+    "game",
+    "build",
+    "upload",
+    "gaming"
+  ],
+  "author": "Ludeo Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ludeo/cli.git"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}
+