@ludeo/cli 1.4.7 → 1.4.8

package/README.md

@@ -27,7 +27,33 @@ 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:
+```bash
+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
 ```bash
@@ -52,21 +78,6 @@ 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"
-```
-
 #### SDK Free Build (Performance testing without Ludeo SDK)
 ```bash
 ludeo builds upload \
@@ -81,11 +92,12 @@ 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)
@@ -93,6 +105,26 @@ ludeo builds upload \
 **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 +143,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
 
@@ -230,4 +264,3 @@ Need help? Here's how to get support:
 3. Contact the Ludeo platform team for additional assistance
 
 For detailed documentation and advanced usage, visit the [Ludeo Developer Portal](https://developers.ludeo.com).
-

package/README.npm.md

@@ -0,0 +1,222 @@
+# 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
+
+### 1. Authentication
+Get your access token from the Ludeo platform and save it:
+```bash
+ludeo auth set-token --access-token YOUR_ACCESS_TOKEN
+```
+
+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:
+```bash
+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
+```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"
+```
+
+#### 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:**
+- `--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
+# 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
+
+```bash
+npm update -g @ludeo/cli
+```
+
+## 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 issues:**
+- Run PowerShell as Administrator
+- Ensure Node.js is properly installed
+
+### 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. Run `npm rebuild @ludeo/cli` if you encounter issues
+3. Contact the Ludeo platform team for additional assistance
+
+For detailed documentation and advanced usage, visit the [Ludeo Developer Portal](https://developers.ludeo.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludeo/cli",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "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,54 @@
+#!/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
+ *
+ * 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 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',
+];
+
+const NPM_EXCLUDE = new Set(['05-testing.md']);
+
+function buildVariant(excludeSet) {
+  const parts = [];
+  for (const name of FRAGMENTS_ORDER) {
+    if (excludeSet && excludeSet.has(name)) continue;
+    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());
+  }
+  return parts.join('\n\n');
+}
+
+function main() {
+  const repoReadme = buildVariant(null);
+  const npmReadme = buildVariant(NPM_EXCLUDE);
+
+  fs.writeFileSync(path.join(ROOT, 'README.md'), repoReadme + '\n', 'utf8');
+  fs.writeFileSync(path.join(ROOT, 'README.npm.md'), npmReadme + '\n', 'utf8');
+
+  console.log('Built README.md (repo, full) and README.npm.md (npm, usage only)');
+}
+
+main();