ludus-cli 0.5.1 → 0.7.0

package/README.md

@@ -10,12 +10,24 @@ Ludus handles the entire workflow that would otherwise require dozens of manual
 npm install -g ludus-cli
 ```
 
+Upgrade to the latest version the same way:
+
+```bash
+npm install -g ludus-cli@latest
+```
+
 Or run directly:
 
 ```bash
 npx ludus-cli --help
 ```
 
+The package downloads a small prebuilt binary on install. If your environment
+blocks install scripts (e.g. `--ignore-scripts`, pnpm, locked-down CI), `ludus`
+fetches the matching binary on first run instead — no extra steps. To manage the
+binary yourself (air-gapped setups), set `LUDUS_SKIP_AUTO_DOWNLOAD=1` and place
+the `ludus` binary under the package's `bin/` directory.
+
 ## What it does
 
 ```

package/install.js

@@ -9,6 +9,7 @@ const { spawnSync } = require("child_process");
 
 const REPO = "jpvelasco/ludus";
 const MAX_REDIRECTS = 5;
+const MARKER = ".installed-version";
 
 const PLATFORM_MAP = {
   linux: "linux",
@@ -21,6 +22,18 @@ const ARCH_MAP = {
   arm64: "arm64",
 };
 
+// log writes routine progress to stderr (never stdout) so it can't corrupt
+// `ludus mcp` JSON-RPC or `--json` output, and stays quiet when silent.
+function log(silent, msg) {
+  if (!silent) {
+    console.error(msg);
+  }
+}
+
+function binaryName(platform = process.platform) {
+  return platform === "win32" ? "ludus.exe" : "ludus";
+}
+
 function getPackageVersion() {
   const pkg = JSON.parse(
     fs.readFileSync(path.join(__dirname, "package.json"), "utf8")
@@ -52,6 +65,21 @@ function getArchiveName(version, platform, arch) {
   return `ludus_${version}_${os}_${cpu}.${ext}`;
 }
 
+// needsDownload reports whether the binary must be (re)fetched: true when the
+// binary is missing, or when the recorded marker version doesn't match the
+// package version (drift after a skipped/failed install or an upgrade).
+function needsDownload(binDir, version) {
+  if (!fs.existsSync(path.join(binDir, binaryName()))) {
+    return true;
+  }
+  try {
+    const installed = fs.readFileSync(path.join(binDir, MARKER), "utf8").trim();
+    return installed !== version;
+  } catch {
+    return true;
+  }
+}
+
 function download(url, redirectCount = 0) {
   return new Promise((resolve, reject) => {
     if (redirectCount > MAX_REDIRECTS) {
@@ -75,10 +103,10 @@ function download(url, redirectCount = 0) {
   });
 }
 
-function verifyChecksum(buffer, archiveName) {
+function verifyChecksum(buffer, archiveName, { silent = false } = {}) {
   const expected = getExpectedChecksum(archiveName);
   if (!expected) {
-    console.log("ludus-cli: no checksum available, skipping verification");
+    log(silent, "ludus-cli: no checksum available, skipping verification");
     return;
   }
 
@@ -90,7 +118,7 @@ function verifyChecksum(buffer, archiveName) {
         `  Actual:   ${actual}`
     );
   }
-  console.log("ludus-cli: checksum verified (SHA-256)");
+  log(silent, "ludus-cli: checksum verified (SHA-256)");
 }
 
 // Escape a string for use inside PowerShell single quotes.
@@ -110,9 +138,25 @@ function spawnOrFail(cmd, args, label) {
   }
 }
 
+// placeBinary moves src onto dest atomically. renameSync is atomic on POSIX and
+// overwrites; on Windows it refuses to overwrite an existing file, so fall back
+// to removing dest first (the binary is never running during a self-heal).
+function placeBinary(src, dest) {
+  try {
+    fs.renameSync(src, dest);
+  } catch (err) {
+    if (err.code === "EEXIST" || err.code === "EPERM") {
+      fs.rmSync(dest, { force: true });
+      fs.renameSync(src, dest);
+    } else {
+      throw err;
+    }
+  }
+}
+
 function extract(buffer, archiveName, binDir) {
-  const tmpDir = path.join(__dirname, ".tmp-install");
-  fs.mkdirSync(tmpDir, { recursive: true });
+  // Unique temp dir per run so concurrent invocations don't clobber each other.
+  const tmpDir = fs.mkdtempSync(path.join(__dirname, ".tmp-install-"));
 
   const archivePath = path.join(tmpDir, archiveName);
   fs.writeFileSync(archivePath, buffer);
@@ -137,48 +181,74 @@ function extract(buffer, archiveName, binDir) {
     }
 
     // Find the binary in the extracted files
-    const binaryName = process.platform === "win32" ? "ludus.exe" : "ludus";
-    const extractedBinary = path.join(tmpDir, binaryName);
+    const bn = binaryName();
+    const extractedBinary = path.join(tmpDir, bn);
 
     if (!fs.existsSync(extractedBinary)) {
-      throw new Error(`Binary ${binaryName} not found in archive`);
+      throw new Error(`Binary ${bn} 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);
+      fs.chmodSync(extractedBinary, 0o755);
     }
+
+    fs.mkdirSync(binDir, { recursive: true });
+    placeBinary(extractedBinary, path.join(binDir, bn));
   } finally {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   }
 }
 
-async function main() {
+// ensureBinary makes the platform binary present and matching the package
+// version, downloading it if missing or stale. It is a no-op (cheap file reads
+// only) when the binary already matches. Safe to call on every CLI invocation.
+// All progress goes to stderr; routine chatter is suppressed when silent.
+async function ensureBinary({ silent = false } = {}) {
   const version = getPackageVersion();
   if (version === "0.0.0") {
-    console.error("ludus-cli: skipping binary download for development version");
+    log(silent, "ludus-cli: skipping binary download for development version");
+    return;
+  }
+
+  const binDir = path.join(__dirname, "bin");
+  if (!needsDownload(binDir, 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}...`);
+  // One concise notice whenever an actual download happens (even when silent),
+  // so a runtime self-heal isn't a silent multi-second hang.
+  console.error(`ludus-cli: fetching ludus binary v${version}...`);
+
+  log(silent, `ludus-cli: downloading ${archiveName}...`);
   const buffer = await download(url);
 
-  verifyChecksum(buffer, archiveName);
+  verifyChecksum(buffer, archiveName, { silent });
 
-  console.log("ludus-cli: extracting binary...");
+  log(silent, "ludus-cli: extracting binary...");
   extract(buffer, archiveName, binDir);
 
-  console.log("ludus-cli: installed successfully");
+  // Marker is written only after the binary is in place, so a crash mid-install
+  // never leaves a marker that falsely claims success.
+  fs.writeFileSync(path.join(binDir, MARKER), version);
+
+  log(silent, "ludus-cli: installed successfully");
 }
 
-main().catch((err) => {
-  console.error(`ludus-cli: installation failed: ${err.message}`);
-  process.exit(1);
-});
+if (require.main === module) {
+  ensureBinary({ silent: false }).catch((err) => {
+    console.error(`ludus-cli: installation failed: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  ensureBinary,
+  needsDownload,
+  getArchiveName,
+  getPackageVersion,
+  binaryName,
+  MARKER,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ludus-cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "UE5 dedicated server deployment CLI with MCP server",
   "license": "MIT",
   "repository": {
@@ -11,7 +11,8 @@
     "ludus": "run.js"
   },
   "scripts": {
-    "postinstall": "node install.js"
+    "postinstall": "node install.js",
+    "test": "node --test"
   },
   "os": [
     "linux",
@@ -45,10 +46,10 @@
     "bin/"
   ],
   "binaryChecksums": {
-    "ludus_0.5.1_darwin_amd64.tar.gz": "801e721ba4dd339bab512537aa123e4c9280a7a5363ef40bfd9d1e7e14a3de01",
-    "ludus_0.5.1_darwin_arm64.tar.gz": "d685fd571e161c5d57369d0b1b3dd833f4db1b3a5c7d5bb8dbc5674edc242e1a",
-    "ludus_0.5.1_linux_amd64.tar.gz": "e5df3d6a72f1543ea839472b1e5decd302d4730ea91beef97296cc74df229069",
-    "ludus_0.5.1_linux_arm64.tar.gz": "152d90ddb78a4083083b077fe3747281f539834667f0a6c237e4c9caa4cd9ca3",
-    "ludus_0.5.1_windows_amd64.zip": "145e9aab871620919d1964072a7ade05bc2b1cdbc654d2b457a7714fd049e4b3"
+    "ludus_0.7.0_darwin_amd64.tar.gz": "6d866a491c343655d9ddfed2e2af6646600ce932df9e92985ca5448fcee09f3d",
+    "ludus_0.7.0_darwin_arm64.tar.gz": "57b21a09beb9d38a8f222f3152fbf9672d1eb7f078ecf1a443e42d04551734e0",
+    "ludus_0.7.0_linux_amd64.tar.gz": "82916ed60bbd128dd767c66812a19083db99d682f370e42a73ae34336bdcd105",
+    "ludus_0.7.0_linux_arm64.tar.gz": "87c112969156723251cdf463fc5fdbc6cf889cd9cfac897bc67e06d64b1675f7",
+    "ludus_0.7.0_windows_amd64.zip": "2befdd47c92c52ae83bad674db36e372e9e4e744e9a362af052ff8cefe94597a"
   }
 }

package/run.js

@@ -3,31 +3,71 @@
 
 const path = require("path");
 const { spawn } = require("child_process");
+const { ensureBinary, binaryName } = require("./install.js");
 
-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}`);
+const binaryPath = path.join(__dirname, "bin", binaryName());
+
+function spawnBinary() {
+  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` +
+          "Reinstall with: npm install -g ludus-cli@latest"
+      );
+    } else {
+      console.error(`ludus-cli: failed to start: ${err.message}`);
+    }
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    process.exit(signal ? 1 : code || 0);
+  });
+}
+
+async function main() {
+  // Escape hatch: deliberately manage the binary yourself / air-gapped setups.
+  // Skip the self-heal and spawn whatever is present (ENOENT guidance if not).
+  if (process.env.LUDUS_SKIP_AUTO_DOWNLOAD) {
+    spawnBinary();
+    return;
+  }
+
+  try {
+    // Self-heal: if postinstall was skipped (ignore-scripts, pnpm), failed
+    // mid-download, or the binary drifted from this package version, fetch the
+    // correct one. No-op (cheap file reads) when already in sync. silent:true
+    // keeps routine chatter off; an actual download still prints one stderr line.
+    await ensureBinary({ silent: true });
+  } catch (err) {
+    const code = err && err.code;
+    if (code === "EACCES" || code === "EPERM") {
+      console.error(
+        `ludus-cli: cannot write the ludus binary (permission denied).\n` +
+          "Reinstall with appropriate privileges:\n" +
+          "  sudo npm install -g ludus-cli@latest    (macOS/Linux)\n" +
+          "  run your shell as Administrator, then the same command (Windows)"
+      );
+    } else {
+      console.error(
+        `ludus-cli: could not fetch the ludus binary: ${err.message}\n` +
+          "Check your network/proxy and retry. If you manage the binary yourself,\n" +
+          "set LUDUS_SKIP_AUTO_DOWNLOAD=1 to bypass this step."
+      );
+    }
+    process.exit(1);
   }
-  process.exit(1);
-});
 
-child.on("exit", (code, signal) => {
-  process.exit(signal ? 1 : code || 0);
-});
+  spawnBinary();
+}
+
+main();