ludus-cli 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,65 @@
+# ludus-cli
+
+CLI tool that automates the end-to-end pipeline for deploying Unreal Engine 5 dedicated servers to AWS GameLift.
+
+Ludus handles the entire workflow that would otherwise require dozens of manual steps across multiple tools: UE5 source builds, game server compilation, Docker containerization, ECR push, and GameLift fleet deployment.
+
+## Install
+
+```bash
+npm install -g ludus-cli
+```
+
+Or run directly:
+
+```bash
+npx ludus-cli --help
+```
+
+## What it does
+
+```
+ludus run --verbose
+```
+
+This single command orchestrates six stages:
+
+1. **Prerequisite validation** — OS, engine source, game content, Docker, AWS CLI, disk space, RAM
+2. **Engine build** — UE5 source compilation
+3. **Game server build** — Dedicated server packaging via RunUAT
+4. **Container build** — Dockerfile generation and Docker image build
+5. **ECR push** — Docker image push to Amazon ECR
+6. **GameLift deploy** — Container fleet creation with IAM roles and polling
+
+## Deployment targets
+
+| Target | Command | Docker required? | ARM64 (Graviton) |
+|--------|---------|:---:|:---:|
+| GameLift Containers | `ludus deploy fleet` | Yes | Yes |
+| CloudFormation Stack | `ludus deploy stack` | Yes | Yes |
+| GameLift Managed EC2 | `ludus deploy ec2` | No | Yes |
+| GameLift Anywhere | `ludus deploy anywhere` | No | No |
+| Binary export | `ludus deploy binary` | No | Yes |
+
+## AI Agent Integration (MCP)
+
+Ludus includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server exposing 21 tools. Any MCP-compatible AI agent can orchestrate the full pipeline programmatically.
+
+```json
+{
+  "mcpServers": {
+    "ludus": {
+      "command": "npx",
+      "args": ["-y", "ludus-cli", "mcp"]
+    }
+  }
+}
+```
+
+## Documentation
+
+Full documentation, configuration reference, and prerequisites: [github.com/jpvelasco/ludus](https://github.com/jpvelasco/ludus)
+
+## License
+
+[MIT](https://github.com/jpvelasco/ludus/blob/main/LICENSE)

package/install.js

@@ -1,184 +1,184 @@
-#!/usr/bin/env node
-"use strict";
-
-const fs = require("fs");
-const path = require("path");
-const https = require("https");
-const crypto = require("crypto");
-const { spawnSync } = require("child_process");
-
-const REPO = "jpvelasco/ludus";
-const MAX_REDIRECTS = 5;
-
-const PLATFORM_MAP = {
-  linux: "linux",
-  darwin: "darwin",
-  win32: "windows",
-};
-
-const ARCH_MAP = {
-  x64: "amd64",
-  arm64: "arm64",
-};
-
-function getPackageVersion() {
-  const pkg = JSON.parse(
-    fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
-  );
-  const version = pkg.version;
-
-  // Validate semver format to prevent URL injection
-  if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/.test(version)) {
-    throw new Error(`Invalid version format: ${version}`);
-  }
-
-  return version;
-}
-
-function getExpectedChecksum(archiveName) {
-  const pkg = JSON.parse(
-    fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
-  );
-  return pkg.binaryChecksums?.[archiveName] || null;
-}
-
-function getArchiveName(version, platform, arch) {
-  const os = PLATFORM_MAP[platform];
-  const cpu = ARCH_MAP[arch];
-  if (!os || !cpu) {
-    throw new Error(`Unsupported platform: ${platform}/${arch}`);
-  }
-  const ext = platform === "win32" ? "zip" : "tar.gz";
-  return `ludus_${version}_${os}_${cpu}.${ext}`;
-}
-
-function download(url, redirectCount = 0) {
-  return new Promise((resolve, reject) => {
-    if (redirectCount > MAX_REDIRECTS) {
-      return reject(new Error(`Too many redirects (max ${MAX_REDIRECTS})`));
-    }
-
-    https
-      .get(url, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          return download(res.headers.location, redirectCount + 1).then(resolve, reject);
-        }
-        if (res.statusCode !== 200) {
-          return reject(new Error(`Download failed: HTTP ${res.statusCode} for ${url}`));
-        }
-        const chunks = [];
-        res.on("data", (chunk) => chunks.push(chunk));
-        res.on("end", () => resolve(Buffer.concat(chunks)));
-        res.on("error", reject);
-      })
-      .on("error", reject);
-  });
-}
-
-function verifyChecksum(buffer, archiveName) {
-  const expected = getExpectedChecksum(archiveName);
-  if (!expected) {
-    console.log("ludus-cli: no checksum available, skipping verification");
-    return;
-  }
-
-  const actual = crypto.createHash("sha256").update(buffer).digest("hex");
-  if (actual !== expected) {
-    throw new Error(
-      `Checksum mismatch for ${archiveName}\n` +
-        `  Expected: ${expected}\n` +
-        `  Actual:   ${actual}`
-    );
-  }
-  console.log("ludus-cli: checksum verified (SHA-256)");
-}
-
-// Escape a string for use inside PowerShell single quotes.
-// PowerShell single-quoted strings only need '' to represent a literal '.
-function psEscape(s) {
-  return s.replace(/'/g, "''");
-}
-
-function spawnOrFail(cmd, args, label) {
-  const result = spawnSync(cmd, args, { stdio: "pipe" });
-  if (result.error) {
-    throw new Error(`${label}: ${result.error.message}`);
-  }
-  if (result.status !== 0) {
-    const stderr = result.stderr ? result.stderr.toString().trim() : "";
-    throw new Error(`${label} exited with code ${result.status}${stderr ? ": " + stderr : ""}`);
-  }
-}
-
-function extract(buffer, archiveName, binDir) {
-  const tmpDir = path.join(__dirname, ".tmp-install");
-  fs.mkdirSync(tmpDir, { recursive: true });
-
-  const archivePath = path.join(tmpDir, archiveName);
-  fs.writeFileSync(archivePath, buffer);
-
-  try {
-    if (archiveName.endsWith(".zip")) {
-      if (process.platform === "win32") {
-        spawnOrFail(
-          "powershell",
-          [
-            "-NoProfile",
-            "-Command",
-            `Expand-Archive -Force -Path '${psEscape(archivePath)}' -DestinationPath '${psEscape(tmpDir)}'`,
-          ],
-          "Expand-Archive"
-        );
-      } else {
-        spawnOrFail("unzip", ["-o", archivePath, "-d", tmpDir], "unzip");
-      }
-    } else {
-      spawnOrFail("tar", ["-xzf", archivePath, "-C", tmpDir], "tar");
-    }
-
-    // Find the binary in the extracted files
-    const binaryName = process.platform === "win32" ? "ludus.exe" : "ludus";
-    const extractedBinary = path.join(tmpDir, binaryName);
-
-    if (!fs.existsSync(extractedBinary)) {
-      throw new Error(`Binary ${binaryName} not found in archive`);
-    }
-
-    fs.mkdirSync(binDir, { recursive: true });
-    const destBinary = path.join(binDir, binaryName);
-    fs.copyFileSync(extractedBinary, destBinary);
-
-    if (process.platform !== "win32") {
-      fs.chmodSync(destBinary, 0o755);
-    }
-  } finally {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
-  }
-}
-
-async function main() {
-  const version = getPackageVersion();
-  if (version === "0.0.0") {
-    console.error("ludus-cli: skipping binary download for development version");
-    return;
-  }
-
-  const archiveName = getArchiveName(version, process.platform, process.arch);
-  const url = `https://github.com/${REPO}/releases/download/v${version}/${archiveName}`;
-  const binDir = path.join(__dirname, "bin");
-
-  console.log(`ludus-cli: downloading ${archiveName}...`);
-  const buffer = await download(url);
-
-  verifyChecksum(buffer, archiveName);
-
-  console.log("ludus-cli: extracting binary...");
-  extract(buffer, archiveName, binDir);
-
-  console.log("ludus-cli: installed successfully");
-}
-
-main().catch((err) => {
-  console.error(`ludus-cli: installation failed: ${err.message}`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+const crypto = require("crypto");
+const { spawnSync } = require("child_process");
+
+const REPO = "jpvelasco/ludus";
+const MAX_REDIRECTS = 5;
+
+const PLATFORM_MAP = {
+  linux: "linux",
+  darwin: "darwin",
+  win32: "windows",
+};
+
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+function getPackageVersion() {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
+  );
+  const version = pkg.version;
+
+  // Validate semver format to prevent URL injection
+  if (!/^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/.test(version)) {
+    throw new Error(`Invalid version format: ${version}`);
+  }
+
+  return version;
+}
+
+function getExpectedChecksum(archiveName) {
+  const pkg = JSON.parse(
+    fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
+  );
+  return pkg.binaryChecksums?.[archiveName] || null;
+}
+
+function getArchiveName(version, platform, arch) {
+  const os = PLATFORM_MAP[platform];
+  const cpu = ARCH_MAP[arch];
+  if (!os || !cpu) {
+    throw new Error(`Unsupported platform: ${platform}/${arch}`);
+  }
+  const ext = platform === "win32" ? "zip" : "tar.gz";
+  return `ludus_${version}_${os}_${cpu}.${ext}`;
+}
+
+function download(url, redirectCount = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirectCount > MAX_REDIRECTS) {
+      return reject(new Error(`Too many redirects (max ${MAX_REDIRECTS})`));
+    }
+
+    https
+      .get(url, (res) => {
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          return download(res.headers.location, redirectCount + 1).then(resolve, reject);
+        }
+        if (res.statusCode !== 200) {
+          return reject(new Error(`Download failed: HTTP ${res.statusCode} for ${url}`));
+        }
+        const chunks = [];
+        res.on("data", (chunk) => chunks.push(chunk));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+        res.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+function verifyChecksum(buffer, archiveName) {
+  const expected = getExpectedChecksum(archiveName);
+  if (!expected) {
+    console.log("ludus-cli: no checksum available, skipping verification");
+    return;
+  }
+
+  const actual = crypto.createHash("sha256").update(buffer).digest("hex");
+  if (actual !== expected) {
+    throw new Error(
+      `Checksum mismatch for ${archiveName}\n` +
+        `  Expected: ${expected}\n` +
+        `  Actual:   ${actual}`
+    );
+  }
+  console.log("ludus-cli: checksum verified (SHA-256)");
+}
+
+// Escape a string for use inside PowerShell single quotes.
+// PowerShell single-quoted strings only need '' to represent a literal '.
+function psEscape(s) {
+  return s.replace(/'/g, "''");
+}
+
+function spawnOrFail(cmd, args, label) {
+  const result = spawnSync(cmd, args, { stdio: "pipe" });
+  if (result.error) {
+    throw new Error(`${label}: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    const stderr = result.stderr ? result.stderr.toString().trim() : "";
+    throw new Error(`${label} exited with code ${result.status}${stderr ? ": " + stderr : ""}`);
+  }
+}
+
+function extract(buffer, archiveName, binDir) {
+  const tmpDir = path.join(__dirname, ".tmp-install");
+  fs.mkdirSync(tmpDir, { recursive: true });
+
+  const archivePath = path.join(tmpDir, archiveName);
+  fs.writeFileSync(archivePath, buffer);
+
+  try {
+    if (archiveName.endsWith(".zip")) {
+      if (process.platform === "win32") {
+        spawnOrFail(
+          "powershell",
+          [
+            "-NoProfile",
+            "-Command",
+            `Expand-Archive -Force -Path '${psEscape(archivePath)}' -DestinationPath '${psEscape(tmpDir)}'`,
+          ],
+          "Expand-Archive"
+        );
+      } else {
+        spawnOrFail("unzip", ["-o", archivePath, "-d", tmpDir], "unzip");
+      }
+    } else {
+      spawnOrFail("tar", ["-xzf", archivePath, "-C", tmpDir], "tar");
+    }
+
+    // Find the binary in the extracted files
+    const binaryName = process.platform === "win32" ? "ludus.exe" : "ludus";
+    const extractedBinary = path.join(tmpDir, binaryName);
+
+    if (!fs.existsSync(extractedBinary)) {
+      throw new Error(`Binary ${binaryName} not found in archive`);
+    }
+
+    fs.mkdirSync(binDir, { recursive: true });
+    const destBinary = path.join(binDir, binaryName);
+    fs.copyFileSync(extractedBinary, destBinary);
+
+    if (process.platform !== "win32") {
+      fs.chmodSync(destBinary, 0o755);
+    }
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+async function main() {
+  const version = getPackageVersion();
+  if (version === "0.0.0") {
+    console.error("ludus-cli: skipping binary download for development version");
+    return;
+  }
+
+  const archiveName = getArchiveName(version, process.platform, process.arch);
+  const url = `https://github.com/${REPO}/releases/download/v${version}/${archiveName}`;
+  const binDir = path.join(__dirname, "bin");
+
+  console.log(`ludus-cli: downloading ${archiveName}...`);
+  const buffer = await download(url);
+
+  verifyChecksum(buffer, archiveName);
+
+  console.log("ludus-cli: extracting binary...");
+  extract(buffer, archiveName, binDir);
+
+  console.log("ludus-cli: installed successfully");
+}
+
+main().catch((err) => {
+  console.error(`ludus-cli: installation failed: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ludus-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "UE5 dedicated server deployment CLI with MCP server",
   "license": "MIT",
   "repository": {
@@ -22,16 +22,33 @@
     "x64",
     "arm64"
   ],
+  "keywords": [
+    "unreal-engine",
+    "ue5",
+    "gamelift",
+    "aws",
+    "dedicated-server",
+    "game-server",
+    "gamedev",
+    "deployment",
+    "docker",
+    "mcp",
+    "cli",
+    "devops",
+    "arm64",
+    "graviton",
+    "buildgraph"
+  ],
   "files": [
     "install.js",
     "run.js",
     "bin/"
   ],
   "binaryChecksums": {
-    "ludus_0.1.1_darwin_amd64.tar.gz": "0d694cfc6dc7bc8a5932af64142726cb9277e56e06995d9506ea892b100b21f9",
-    "ludus_0.1.1_darwin_arm64.tar.gz": "3e5c420a0acfe2b5a0ada39af8ef4c1b191626460aa60fc997d2bcfeb40535d4",
-    "ludus_0.1.1_linux_amd64.tar.gz": "cd230ca2b080986021adadd14e086555e021bfeee5eca3b5cc78f5146f6114a8",
-    "ludus_0.1.1_linux_arm64.tar.gz": "bd96a2a04a9af979c2bd6815fcc10c4bc9460b9a8aa8d06d898ad6202df10483",
-    "ludus_0.1.1_windows_amd64.zip": "7abe8327e3df427423516c34fe6382addbbde5ec7669617a97abd999d68de6cb"
+    "ludus_0.1.3_darwin_amd64.tar.gz": "ed0d7715e05b1cdac42a0f71aca557c0ad3b99952abcddf4eccd1bab37222fd1",
+    "ludus_0.1.3_darwin_arm64.tar.gz": "bbb49935b47d115f3e3e24bcd65aabe1be0cea2bdf039aec747849d709c21146",
+    "ludus_0.1.3_linux_amd64.tar.gz": "9a3093291d5b87c406af37a51750ac5b60e49758cf310ce03d1f6acba6dfb64d",
+    "ludus_0.1.3_linux_arm64.tar.gz": "d33be20dc2e6accb94a548df13981510265699dffc1dc278867e79f258b7bc9b",
+    "ludus_0.1.3_windows_amd64.zip": "b308f043e16c6abba1f7e995cdd4955a7e4d2105301ce413b7f82719d1e85c36"
   }
 }

package/run.js

@@ -1,33 +1,33 @@
-#!/usr/bin/env node
-"use strict";
-
-const path = require("path");
-const { spawn } = require("child_process");
-
-const binaryName = process.platform === "win32" ? "ludus.exe" : "ludus";
-const binaryPath = path.join(__dirname, "bin", binaryName);
-
-const child = spawn(binaryPath, process.argv.slice(2), {
-  stdio: "inherit",
-});
-
-// Forward signals so the Go binary shuts down cleanly
-["SIGINT", "SIGTERM", "SIGHUP"].forEach((sig) => {
-  process.on(sig, () => child.kill(sig));
-});
-
-child.on("error", (err) => {
-  if (err.code === "ENOENT") {
-    console.error(
-      `ludus-cli: binary not found at ${binaryPath}\n` +
-        "Run 'npm rebuild ludus-cli' or reinstall the package."
-    );
-  } else {
-    console.error(`ludus-cli: failed to start: ${err.message}`);
-  }
-  process.exit(1);
-});
-
-child.on("exit", (code, signal) => {
-  process.exit(signal ? 1 : code || 0);
-});
+#!/usr/bin/env node
+"use strict";
+
+const path = require("path");
+const { spawn } = require("child_process");
+
+const binaryName = process.platform === "win32" ? "ludus.exe" : "ludus";
+const binaryPath = path.join(__dirname, "bin", binaryName);
+
+const child = spawn(binaryPath, process.argv.slice(2), {
+  stdio: "inherit",
+});
+
+// Forward signals so the Go binary shuts down cleanly
+["SIGINT", "SIGTERM", "SIGHUP"].forEach((sig) => {
+  process.on(sig, () => child.kill(sig));
+});
+
+child.on("error", (err) => {
+  if (err.code === "ENOENT") {
+    console.error(
+      `ludus-cli: binary not found at ${binaryPath}\n` +
+        "Run 'npm rebuild ludus-cli' or reinstall the package."
+    );
+  } else {
+    console.error(`ludus-cli: failed to start: ${err.message}`);
+  }
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  process.exit(signal ? 1 : code || 0);
+});