add support to inject custom bedrock_server.exe

Author: SupaHam

packages/blr/docs/reference/generated-project.md

@@ -173,6 +173,18 @@ Optional project state file.
 
 If present, `blr` applies it to BDS permissions state.
 
+### `server/bedrock_server.exe`
+
+Optional project state file for Windows local-server runs.
+
+If present, `blr` copies it into the resolved runtime BDS server directory and uses it as the local-server executable override.
+
+Notes:
+
+- this overrides the provisioned `bedrock_server.exe` in the runtime BDS folder
+- if the runtime BDS server is already provisioned, `blr` reuses that server and applies the override without re-downloading the stock archive
+- `blr dev` prints a notice when the override is active
+
 ## Generated Support Files
 
 ### `.gitignore`

packages/blr/src/bds.ts

@@ -1,6 +1,6 @@
 import { spawn, type ChildProcess } from "node:child_process";
 import path from "node:path";
-import { mkdtemp, rename, writeFile } from "node:fs/promises";
+import { chmod, copyFile, mkdtemp, rename, writeFile } from "node:fs/promises";
 import { createInterface, type Interface } from "node:readline";
 import AdmZip from "adm-zip";
 import { resolveDirectBedrockDownloadUrl } from "./bedrock-downloads.js";
@@ -13,6 +13,7 @@ import { resolveProjectRelativePath } from "./environment.js";
 import {
     copyDirectory,
     ensureDirectory,
+    ensureParentDirectory,
     exists,
     readJson,
     readText,
@@ -34,7 +35,10 @@ import {
     resolveConfiguredWorldSourcePath,
     resolveProjectWorldSourceDirectory,
 } from "./world.js";
-import { resolveProjectServerStatePath } from "./server-state.js";
+import {
+    PROJECT_SERVER_STATE_ROOT,
+    resolveProjectServerStatePath,
+} from "./server-state.js";
 
 type AllowlistEntry = {
     xuid: string;
@@ -63,6 +67,8 @@ export type ResolvedBdsState = {
     worldSourceDirectory: string;
     executablePath: string;
     zipPath: string;
+    customExecutableSourcePath?: string;
+    customExecutableInjected: boolean;
 };
 
 function resolveBdsPlatform(
@@ -120,9 +126,48 @@ export function resolveBdsRuntimeState(
                 ? `bedrock-server-preview-${version}-${platform}.zip`
                 : `bedrock-server-${version}-${platform}.zip`,
         ),
+        customExecutableInjected: false,
     };
 }
 
+function resolveProjectCustomExecutablePath(
+    projectRoot: string,
+    state: ResolvedBdsState,
+): string {
+    return path.join(
+        projectRoot,
+        PROJECT_SERVER_STATE_ROOT,
+        path.basename(state.executablePath),
+    );
+}
+
+async function applyCustomExecutableOverride(
+    projectRoot: string,
+    state: ResolvedBdsState,
+    debug?: DebugLogger,
+): Promise<void> {
+    const customExecutableSourcePath = resolveProjectCustomExecutablePath(
+        projectRoot,
+        state,
+    );
+    if (!(await exists(customExecutableSourcePath))) {
+        return;
+    }
+
+    await ensureParentDirectory(state.executablePath);
+    await copyFile(customExecutableSourcePath, state.executablePath);
+    if (state.platform === "linux") {
+        await chmod(state.executablePath, 0o755);
+    }
+
+    state.customExecutableSourcePath = customExecutableSourcePath;
+    state.customExecutableInjected = true;
+    debug?.log("bds", "applied custom BDS executable override", {
+        sourcePath: customExecutableSourcePath,
+        executablePath: state.executablePath,
+    });
+}
+
 async function downloadIfMissing(
     state: ResolvedBdsState,
     debug?: DebugLogger,
@@ -363,6 +408,7 @@ async function extractIfMissing(
             await readProjectPermissions(projectRoot, config),
         );
         await ensureModulePermissions(state.serverDirectory);
+        await applyCustomExecutableOverride(projectRoot, state, debug);
         return;
     }
 
@@ -418,6 +464,7 @@ async function extractIfMissing(
         await readProjectPermissions(projectRoot, config),
     );
     await ensureModulePermissions(state.serverDirectory);
+    await applyCustomExecutableOverride(projectRoot, state, debug);
 }
 
 async function copyBuiltArtifacts(
@@ -889,6 +936,21 @@ export class BdsServerController {
             return;
         }
 
+        if (state.customExecutableInjected) {
+            const sourceLabel = state.customExecutableSourcePath
+                ? path.relative(
+                      this.projectRoot,
+                      state.customExecutableSourcePath,
+                  )
+                : path.join(
+                      PROJECT_SERVER_STATE_ROOT,
+                      path.basename(state.executablePath),
+                  );
+            console.log(
+                `[dev] Notice: using custom local-server executable override from ${sourceLabel}.`,
+            );
+        }
+
         this.options.debug?.log("bds", "starting managed server", {
             executablePath: state.executablePath,
             cwd: state.serverDirectory,

packages/blr/test/bds.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { access } from "node:fs/promises";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import test from "node:test";
 import { ensureBds } from "../src/bds.js";
@@ -74,3 +74,76 @@ test("ensureBds does not leave a versioned server directory behind after an inva
     assert.equal(await pathExists(serverDirectory), false);
     assert.equal(await pathExists(cacheZipPath), false);
 });
+
+test("ensureBds applies server/bedrock_server.exe as a custom local-server override without downloading", async (t) => {
+    const projectRoot = await createTempDirectory(t, "blr-bds-custom-");
+    const version = "1.26.3.1";
+    const runtimeServerDirectory = path.join(
+        projectRoot,
+        ".blr",
+        "bds",
+        version,
+        "server",
+    );
+    const runtimeExecutablePath = path.join(
+        runtimeServerDirectory,
+        "bedrock_server.exe",
+    );
+    const customExecutablePath = path.join(
+        projectRoot,
+        "server",
+        "bedrock_server.exe",
+    );
+
+    await mkdir(path.join(runtimeServerDirectory, "config", "default"), {
+        recursive: true,
+    });
+    await writeFile(runtimeExecutablePath, "stock executable");
+    await writeFile(
+        path.join(runtimeServerDirectory, "server.properties"),
+        "level-name=Bedrock level\n",
+    );
+    await mkdir(path.dirname(customExecutablePath), { recursive: true });
+    await writeFile(customExecutablePath, "custom executable");
+
+    t.mock.method(globalThis, "fetch", async () => {
+        throw new Error("fetch should not be called");
+    });
+
+    const state = await ensureBds(
+        projectRoot,
+        {
+            minecraft: {
+                channel: "stable",
+            },
+            dev: {
+                localServer: {
+                    worldName: "Bedrock level",
+                    worldSourcePath: "worlds/Bedrock level",
+                    defaultPermissionLevel: "member",
+                    gamemode: "survival",
+                    allowlist: [],
+                    operators: [],
+                },
+            },
+            world: {
+                backend: "local",
+            },
+        } as any,
+        {
+            localServer: {
+                bdsVersion: version,
+                platform: "win",
+                cacheDirectory: ".blr/cache/bds",
+                serverDirectory: `.blr/bds/${version}/server`,
+            },
+        } as any,
+    );
+
+    assert.equal(
+        await readFile(runtimeExecutablePath, "utf8"),
+        "custom executable",
+    );
+    assert.equal(state.customExecutableInjected, true);
+    assert.equal(state.customExecutableSourcePath, customExecutablePath);
+});