@ludeo/cli 1.4.7 → 1.4.9

package/README.md

@@ -15,21 +15,66 @@ ludeo version
 
 ## Quick Start
 
+### Getting Your Game ID and Access Token
+Both your **Game ID** and **Access Token** are available in the [Studio Lab](https://studio.ludeo.com) under **Environments**.
+
+- **Access Token:** In Environments, click **Create Token**, name it, then copy and save the token (you won’t be able to see it again).
+- **Game ID:** In Environments, it’s shown at the top of the page next to the API key.
+
 ### 1. Authentication
-Get your access token from the Ludeo platform and save it:
+Save your access token:
+
+**macOS / Linux:**
 ```bash
 ludeo auth set-token --access-token YOUR_ACCESS_TOKEN
 ```
 
+**Windows (Command Prompt):** use the same command; for multi-line commands use `^` at the end of each line instead of `\`.
+
 You can also check if a token is saved:
 ```bash
 ludeo auth status
 ```
 
 ### 2. Upload Your Build
-Upload your game build with a simple command. The CLI supports three build creation types:
+
+#### Interactive Mode (Recommended for First-Time Users)
+Simply run the upload command without flags to start the interactive wizard:
+
+**macOS / Linux:**
+```bash
+ludeo builds upload
+```
+
+**Windows (Command Prompt):**
+```cmd
+ludeo builds upload
+```
+
+The interactive mode will guide you through:
+1. **Game ID** - Enter your game's unique identifier
+2. **Build Creation Type** - Choose between `new`, or `sdkFree`
+3. **Build Type** - Select `major` or `minor` (with warning for major builds)
+4. **Major Version Selection** - If creating a minor build, select from existing major versions
+5. **Game Version** - Enter the version number (e.g., 1.2.3)
+6. **SDK Version** - Enter the Ludeo SDK version (not required for sdkFree)
+7. **Executable Path** - Path to your game executable relative to build directory
+8. **Local Directory** - Path to your build files
+9. **Changes Description** - Optional description of what changed
+
+Before uploading, you'll see a summary of all options and the equivalent CLI command for future use in scripts or CI/CD pipelines.
+
+To disable interactive mode (for CI/CD or scripts):
+```bash
+ludeo builds upload --no-interactive [flags...]
+```
+
+#### Command-Line Mode
+Upload your game build with a simple command. The CLI supports two build creation types (**modification builds are not supported from the CLI—use [Studio Labs](https://studio.ludeo.com) for those**):
 
 #### New Build (Complete build from scratch) - DEFAULT
+
+**macOS / Linux:**
 ```bash
 # With explicit build-creation-type
 ludeo builds upload \
@@ -52,19 +97,16 @@ ludeo builds upload \
   --sdk-version "2.0.0"
 ```
 
-#### Modification Build (Based on an existing build)
-```bash
-ludeo builds upload \
-  --game-id YOUR_GAME_ID \
-  --exec-path game.exe \
-  --local-directory ./builds \
-  --build-creation-type modification \
-  --build-type minor \
-  --game-version "1.2.4" \
-  --sdk-version "2.0.0" \
-  --base-build-id EXISTING_BUILD_ID \
-  --major-build-id MAJOR_BUILD_ID \
-  --changes-description "Minor bug fixes"
+**Windows (Command Prompt):** use `^` at the end of each line for continuation:
+```cmd
+ludeo builds upload ^
+  --game-id YOUR_GAME_ID ^
+  --exec-path "game.exe" ^
+  --local-directory "C:\path\to\your\builds" ^
+  --build-creation-type new ^
+  --build-type major ^
+  --game-version "1.2.3" ^
+  --sdk-version "2.0.0"
 ```
 
 #### SDK Free Build (Performance testing without Ludeo SDK)
@@ -81,18 +123,38 @@ ludeo builds upload \
 
 ### 3. Build Types and Requirements
 
-**Build Creation Types:**
+**Build Creation Types (CLI):**
 - `new`: Complete build from scratch (requires game-version, sdk-version, build-type) **[DEFAULT]**
-- `modification`: Based on an existing build (requires base-build-id, game-version, sdk-version, build-type)
 - `sdkFree`: Performance testing without Ludeo SDK (requires game-version, build-type; sdk-version not required)
 
+**Note:** Modification builds (builds based on an existing build) are **not supported from the CLI**. Create modification builds from [Studio Labs](https://studio.ludeo.com) only.
+
 **Build Types:**
 - `major`: Major version build
 - `minor`: Minor version build (requires major-build-id)
 
 **Additional Flags:**
-- `--runtime-environment`: Runtime environment (windows/proton) - only available for Ludeo admins
 - `--request-id`: Optional request ID for tracking
+- `--no-interactive`: Disable interactive prompts (for CI/CD or scripts)
+- `--dry-run`: Preview the upload without making any changes
+
+#### Dry-Run Mode
+Preview what would be uploaded without making any changes:
+```bash
+ludeo builds upload --dry-run \
+  --game-id YOUR_GAME_ID \
+  --exec-path game.exe \
+  --local-directory ./builds \
+  --build-type major \
+  --game-version "1.2.3" \
+  --sdk-version "2.0.0"
+```
+
+Dry-run will:
+- Validate all parameters and directory structure
+- Scan and display all files that would be uploaded
+- Show total file count and size
+- NOT create any build metadata or upload files
 
 ### 4. Manage Builds
 ```bash
@@ -111,9 +173,11 @@ ludeo auth logout
 
 ## Features
 
+- **Interactive Mode**: Guided wizard for easy build uploads - just run `ludeo builds upload` and follow the prompts
 - **Easy Upload**: Upload complete game builds with a single command
 - **Large File Support**: Automatically handles large files and multiple files
 - **Progress Tracking**: Real-time progress updates during uploads
+- **Dry-Run Mode**: Preview uploads without making changes using `--dry-run`
 - **Cross-Platform**: Works on Windows, macOS, and Linux
 - **Automatic Updates**: Keep your CLI up to date with npm
 
@@ -163,10 +227,13 @@ The test suite includes:
 
 ## Updating
 
+**npm:** 
 ```bash
 npm update -g @ludeo/cli
 ```
 
+**Windows (standalone exe):** download the latest release from the [GitHub releases](https://github.com/ludeo/cli/releases) page and replace your existing executable.
+
 ## CI/CD Integration
 
 ### GitHub Actions
@@ -201,10 +268,15 @@ npm rebuild @ludeo/cli
 sudo npm install -g @ludeo/cli
 ```
 
-**Windows issues:**
+**Windows (npm):**
 - Run PowerShell as Administrator
 - Ensure Node.js is properly installed
 
+**Windows (standalone exe):**
+- **"ludeo is not recognized"** — Add the folder containing `ludeo.exe` to your PATH.
+- **"Access denied" / "Permission denied"** — Right-click the executable → Properties → Unblock → OK, or run Command Prompt as Administrator.
+- **Antivirus blocking** — Add an exception for the executable in your antivirus software.
+
 ### Common Issues
 
 **Authentication errors:**
@@ -226,8 +298,7 @@ sudo npm install -g @ludeo/cli
 Need help? Here's how to get support:
 
 1. Check this README and troubleshooting section
-2. Run `npm rebuild @ludeo/cli` if you encounter issues
+2. **npm:** run `npm rebuild @ludeo/cli` if you encounter issues. **Windows (standalone):** ensure `ludeo.exe` is in your PATH and see the troubleshooting section above.
 3. Contact the Ludeo platform team for additional assistance
 
-For detailed documentation and advanced usage, visit the [Ludeo Developer Portal](https://developers.ludeo.com).
-
+For detailed documentation and advanced usage, visit the [Ludeo Developer Portal](https://developers.ludeo.com) or [Ludeo CLI Documentation](https://docs.ludeo.com/cli).

package/README.npm.md

@@ -0,0 +1,260 @@
+# Ludeo CLI
+
+The official Ludeo CLI tool for uploading game builds to the Ludeo platform. Install via npm for easy setup and automatic updates.
+
+## Installation
+
+```bash
+npm install -g @ludeo/cli
+```
+
+Verify the installation:
+```bash
+ludeo version
+```
+
+## Quick Start
+
+### Getting Your Game ID and Access Token
+Both your **Game ID** and **Access Token** are available in the [Studio Lab](https://studio.ludeo.com) under **Environments**.
+
+- **Access Token:** In Environments, click **Create Token**, name it, then copy and save the token (you won’t be able to see it again).
+- **Game ID:** In Environments, it’s shown at the top of the page next to the API key.
+
+### 1. Authentication
+Save your access token:
+
+**macOS / Linux:**
+```bash
+ludeo auth set-token --access-token YOUR_ACCESS_TOKEN
+```
+
+**Windows (Command Prompt):** use the same command; for multi-line commands use `^` at the end of each line instead of `\`.
+
+You can also check if a token is saved:
+```bash
+ludeo auth status
+```
+
+### 2. Upload Your Build
+
+#### Interactive Mode (Recommended for First-Time Users)
+Simply run the upload command without flags to start the interactive wizard:
+
+**macOS / Linux:**
+```bash
+ludeo builds upload
+```
+
+**Windows (Command Prompt):**
+```cmd
+ludeo builds upload
+```
+
+The interactive mode will guide you through:
+1. **Game ID** - Enter your game's unique identifier
+2. **Build Creation Type** - Choose between `new`, or `sdkFree`
+3. **Build Type** - Select `major` or `minor` (with warning for major builds)
+4. **Major Version Selection** - If creating a minor build, select from existing major versions
+5. **Game Version** - Enter the version number (e.g., 1.2.3)
+6. **SDK Version** - Enter the Ludeo SDK version (not required for sdkFree)
+7. **Executable Path** - Path to your game executable relative to build directory
+8. **Local Directory** - Path to your build files
+9. **Changes Description** - Optional description of what changed
+
+Before uploading, you'll see a summary of all options and the equivalent CLI command for future use in scripts or CI/CD pipelines.
+
+To disable interactive mode (for CI/CD or scripts):
+```bash
+ludeo builds upload --no-interactive [flags...]
+```
+
+#### Command-Line Mode
+Upload your game build with a simple command. The CLI supports two build creation types (**modification builds are not supported from the CLI—use [Studio Labs](https://studio.ludeo.com) for those**):
+
+#### New Build (Complete build from scratch) - DEFAULT
+
+**macOS / Linux:**
+```bash
+# With explicit build-creation-type
+ludeo builds upload \
+  --game-id YOUR_GAME_ID \
+  --exec-path game.exe \
+  --local-directory ./builds \
+  --build-creation-type new \
+  --build-type major \
+  --game-version "1.2.3" \
+  --sdk-version "2.0.0" \
+  --changes-description "Bug fixes and performance improvements"
+
+# Or simply omit --build-creation-type (defaults to "new")
+ludeo builds upload \
+  --game-id YOUR_GAME_ID \
+  --exec-path game.exe \
+  --local-directory ./builds \
+  --build-type major \
+  --game-version "1.2.3" \
+  --sdk-version "2.0.0"
+```
+
+**Windows (Command Prompt):** use `^` at the end of each line for continuation:
+```cmd
+ludeo builds upload ^
+  --game-id YOUR_GAME_ID ^
+  --exec-path "game.exe" ^
+  --local-directory "C:\path\to\your\builds" ^
+  --build-creation-type new ^
+  --build-type major ^
+  --game-version "1.2.3" ^
+  --sdk-version "2.0.0"
+```
+
+#### SDK Free Build (Performance testing without Ludeo SDK)
+```bash
+ludeo builds upload \
+  --game-id YOUR_GAME_ID \
+  --exec-path game.exe \
+  --local-directory ./builds \
+  --build-creation-type sdkFree \
+  --build-type major \
+  --game-version "1.2.3" \
+  --changes-description "Performance testing build"
+```
+
+### 3. Build Types and Requirements
+
+**Build Creation Types (CLI):**
+- `new`: Complete build from scratch (requires game-version, sdk-version, build-type) **[DEFAULT]**
+- `sdkFree`: Performance testing without Ludeo SDK (requires game-version, build-type; sdk-version not required)
+
+**Note:** Modification builds (builds based on an existing build) are **not supported from the CLI**. Create modification builds from [Studio Labs](https://studio.ludeo.com) only.
+
+**Build Types:**
+- `major`: Major version build
+- `minor`: Minor version build (requires major-build-id)
+
+**Additional Flags:**
+- `--request-id`: Optional request ID for tracking
+- `--no-interactive`: Disable interactive prompts (for CI/CD or scripts)
+- `--dry-run`: Preview the upload without making any changes
+
+#### Dry-Run Mode
+Preview what would be uploaded without making any changes:
+```bash
+ludeo builds upload --dry-run \
+  --game-id YOUR_GAME_ID \
+  --exec-path game.exe \
+  --local-directory ./builds \
+  --build-type major \
+  --game-version "1.2.3" \
+  --sdk-version "2.0.0"
+```
+
+Dry-run will:
+- Validate all parameters and directory structure
+- Scan and display all files that would be uploaded
+- Show total file count and size
+- NOT create any build metadata or upload files
+
+### 4. Manage Builds
+```bash
+# List your builds
+ludeo builds list --game-id YOUR_GAME_ID
+
+# Get build details
+ludeo builds get --game-id YOUR_GAME_ID --build-id BUILD_ID
+
+# Check if token is saved
+ludeo auth status
+
+# Remove saved token when done
+ludeo auth logout
+```
+
+## Features
+
+- **Interactive Mode**: Guided wizard for easy build uploads - just run `ludeo builds upload` and follow the prompts
+- **Easy Upload**: Upload complete game builds with a single command
+- **Large File Support**: Automatically handles large files and multiple files
+- **Progress Tracking**: Real-time progress updates during uploads
+- **Dry-Run Mode**: Preview uploads without making changes using `--dry-run`
+- **Cross-Platform**: Works on Windows, macOS, and Linux
+- **Automatic Updates**: Keep your CLI up to date with npm
+
+## Updating
+
+**npm:** 
+```bash
+npm update -g @ludeo/cli
+```
+
+**Windows (standalone exe):** download the latest release from the [GitHub releases](https://github.com/ludeo/cli/releases) page and replace your existing executable.
+
+## CI/CD Integration
+
+### GitHub Actions
+```yaml
+- name: Install Ludeo CLI
+  run: npm install -g @ludeo/cli
+
+- name: Upload Build
+  run: |
+    ludeo auth set-token --access-token ${{ secrets.LUDEO_ACCESS_TOKEN }}
+    ludeo builds upload \
+      --game-id ${{ env.GAME_ID }} \
+      --exec-path game.exe \
+      --local-directory ./builds \
+      --build-creation-type new \
+      --build-type major \
+      --game-version ${{ env.GAME_VERSION }} \
+      --sdk-version ${{ env.SDK_VERSION }}
+```
+
+## Troubleshooting
+
+### Installation Issues
+
+**Binary not found error:**
+```bash
+npm rebuild @ludeo/cli
+```
+
+**Permission issues (macOS/Linux):**
+```bash
+sudo npm install -g @ludeo/cli
+```
+
+**Windows (npm):**
+- Run PowerShell as Administrator
+- Ensure Node.js is properly installed
+
+**Windows (standalone exe):**
+- **"ludeo is not recognized"** — Add the folder containing `ludeo.exe` to your PATH.
+- **"Access denied" / "Permission denied"** — Right-click the executable → Properties → Unblock → OK, or run Command Prompt as Administrator.
+- **Antivirus blocking** — Add an exception for the executable in your antivirus software.
+
+### Common Issues
+
+**Authentication errors:**
+- Verify your access token is valid
+- Check if token is saved with `ludeo auth status`
+- Make sure you've saved your token with `ludeo auth set-token`
+
+**Upload failures:**
+- Ensure your build directory exists and is readable
+- Check your internet connection
+- Verify file paths are correct
+
+**Large files:**
+- Large files may take time to upload
+- Ensure stable internet connection
+
+## Support
+
+Need help? Here's how to get support:
+
+1. Check this README and troubleshooting section
+2. **npm:** run `npm rebuild @ludeo/cli` if you encounter issues. **Windows (standalone):** ensure `ludeo.exe` is in your PATH and see the troubleshooting section above.
+3. Contact the Ludeo platform team for additional assistance
+
+For detailed documentation and advanced usage, visit the [Ludeo Developer Portal](https://developers.ludeo.com) or [Ludeo CLI Documentation](https://docs.ludeo.com/cli).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludeo/cli",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "Ludeo CLI - Upload game builds and manage content on the Ludeo platform",
   "main": "index.js",
   "bin": {
@@ -26,6 +26,7 @@
   ],
   "author": "Ludeo Team",
   "license": "MIT",
+  "readme": "README.npm.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ludeo/cli.git"
@@ -37,7 +38,8 @@
     "bin/",
     "dist/",
     "scripts/",
-    "LICENSE"
+    "LICENSE",
+    "README.npm.md"
   ],
   "os": [
     "win32",

package/scripts/build-readme.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Build README variants from docs/readme/*.md fragments.
+ * - README.md = full (repo, includes Testing) — for GitHub
+ * - README.npm.md = usage only (no Testing) — for NPM package page
+ * - windows-releases/template/README.md = Windows release (docs/readme + docs/readme-windows overrides)
+ *
+ * Run: node scripts/build-readme.js
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const README_DIR = path.join(ROOT, 'docs', 'readme');
+const README_WINDOWS_DIR = path.join(ROOT, 'docs', 'readme-windows');
+
+const FRAGMENTS_ORDER = [
+  '01-title-intro.md',
+  '02-installation.md',
+  '03-quick-start.md',
+  '04-features.md',
+  '05-testing.md',
+  '06-updating.md',
+  '07-cicd.md',
+  '08-troubleshooting.md',
+  '09-support.md',
+];
+
+/** Windows README: Windows-only title + installation, then shared 03–09 (skip 02 npm install, skip 05 testing), then Windows file-info/license */
+const WINDOWS_HEAD = ['01-title-overview.md', '02-installation.md'];
+const WINDOWS_TAIL = ['09-file-info-license.md'];
+const WINDOWS_FROM_README = ['03-quick-start.md', '04-features.md', '06-updating.md', '07-cicd.md', '08-troubleshooting.md', '09-support.md'];
+
+const NPM_EXCLUDE = new Set(['05-testing.md']);
+
+function buildVariant(dir, order, excludeSet) {
+  const parts = [];
+  for (const name of order) {
+    if (excludeSet && excludeSet.has(name)) continue;
+    const file = path.join(dir, name);
+    if (!fs.existsSync(file)) {
+      console.warn(`Warning: fragment missing: ${name}`);
+      continue;
+    }
+    parts.push(fs.readFileSync(file, 'utf8').trim());
+  }
+  return parts.join('\n\n');
+}
+
+function buildWindowsReadme() {
+  const parts = [];
+  for (const name of WINDOWS_HEAD) {
+    const file = path.join(README_WINDOWS_DIR, name);
+    if (!fs.existsSync(file)) {
+      console.warn(`Warning: Windows fragment missing: ${name}`);
+      continue;
+    }
+    parts.push(fs.readFileSync(file, 'utf8').trim());
+  }
+  for (const name of WINDOWS_FROM_README) {
+    const file = path.join(README_DIR, name);
+    if (!fs.existsSync(file)) {
+      console.warn(`Warning: fragment missing: ${name}`);
+      continue;
+    }
+    parts.push(fs.readFileSync(file, 'utf8').trim());
+  }
+  for (const name of WINDOWS_TAIL) {
+    const file = path.join(README_WINDOWS_DIR, name);
+    if (!fs.existsSync(file)) {
+      console.warn(`Warning: Windows fragment missing: ${name}`);
+      continue;
+    }
+    parts.push(fs.readFileSync(file, 'utf8').trim());
+  }
+  return parts.join('\n\n');
+}
+
+function main() {
+  const repoReadme = buildVariant(README_DIR, FRAGMENTS_ORDER, null);
+  const npmReadme = buildVariant(README_DIR, FRAGMENTS_ORDER, NPM_EXCLUDE);
+  const windowsReadme = buildWindowsReadme();
+
+  fs.writeFileSync(path.join(ROOT, 'README.md'), repoReadme + '\n', 'utf8');
+  fs.writeFileSync(path.join(ROOT, 'README.npm.md'), npmReadme + '\n', 'utf8');
+
+  const windowsTemplateDir = path.join(ROOT, 'windows-releases', 'template');
+  if (!fs.existsSync(windowsTemplateDir)) {
+    fs.mkdirSync(windowsTemplateDir, { recursive: true });
+  }
+  fs.writeFileSync(path.join(windowsTemplateDir, 'README.md'), windowsReadme + '\n', 'utf8');
+
+  console.log('Built README.md (repo), README.npm.md (npm), windows-releases/template/README.md (Windows)');
+}
+
+main();

package/scripts/postinstall.js

@@ -2,60 +2,36 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
-// Copy the appropriate binary to dist/ directory
 function postinstall() {
   const platform = os.platform();
   const arch = os.arch();
-  
-  // Map Node.js arch to Go arch
-  const archMap = {
-    'x64': 'amd64',
-    'arm64': 'arm64'
-  };
-  
+
+  const archMap = { 'x64': 'amd64', 'arm64': 'arm64' };
+  const platformMap = { 'win32': 'windows', 'darwin': 'darwin', 'linux': 'linux' };
+
   const goArch = archMap[arch] || arch;
-  
-  // Map platform names
-  const platformMap = {
-    'win32': 'windows',
-    'darwin': 'darwin',
-    'linux': 'linux'
-  };
-  
   const goPlatform = platformMap[platform] || platform;
-  
-  // Construct binary names
-  const sourceBinaryName = platform === 'win32' 
+
+  const binaryName = platform === 'win32'
     ? `ludeo-${goPlatform}-${goArch}.exe`
     : `ludeo-${goPlatform}-${goArch}`;
-  
-  const targetBinaryName = platform === 'win32' ? 'ludeo.exe' : 'ludeo';
-  
-  const sourcePath = path.join(__dirname, '..', 'build', sourceBinaryName);
-  const distDir = path.join(__dirname, '..', 'dist');
-  const targetPath = path.join(distDir, targetBinaryName);
-  
-  // Create dist directory if it doesn't exist
-  if (!fs.existsSync(distDir)) {
-    fs.mkdirSync(distDir, { recursive: true });
-  }
-  
-  // Copy the binary
-  if (fs.existsSync(sourcePath)) {
-    fs.copyFileSync(sourcePath, targetPath);
-    
-    // Make executable on Unix systems
+
+  const distPath = path.join(__dirname, '..', 'dist', binaryName);
+
+  if (fs.existsSync(distPath)) {
     if (platform !== 'win32') {
-      fs.chmodSync(targetPath, '755');
+      fs.chmodSync(distPath, '755');
     }
-    
-    console.log(`✅ Ludeo CLI binary installed: ${targetPath}`);
-  } else {
-    console.warn(`⚠️  Warning: Binary not found at ${sourcePath}`);
-    console.warn('This might happen during development. Run "npm run build" first.');
+    return;
+  }
+
+  // Only warn in development (when installing from source with build/ directory)
+  const buildPath = path.join(__dirname, '..', 'build', binaryName);
+  if (!fs.existsSync(buildPath)) {
+    console.warn(`⚠️  Ludeo CLI: binary not found for ${platform}-${arch}.`);
+    console.warn('Try running: npm rebuild @ludeo/cli');
   }
 }
 
-// Run postinstall
 postinstall();