@nativedesktop/host 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativedesktop/host",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Resolves the prebuilt NativeDesktop host binary for the current platform",
   "type": "module",
   "license": "MIT",
@@ -12,16 +12,18 @@
   "homepage": "https://github.com/FormalSnake/NativeDesktop#readme",
   "bugs": "https://github.com/FormalSnake/NativeDesktop/issues",
   "publishConfig": {
-  "access": "public"
-},
-"files": ["src"],
-"main": "./src/index.ts",
-"types": "./src/index.ts",
-"exports": {
-  ".": "./src/index.ts"
-},
-"optionalDependencies": {
-  "@nativedesktop/host-darwin-arm64": "0.1.0",
-  "@nativedesktop/host-linux-x64": "0.1.0"
-}
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "optionalDependencies": {
+    "@nativedesktop/host-darwin-arm64": "0.2.0",
+    "@nativedesktop/host-linux-x64": "0.2.0"
+  }
 }

package/src/index.test.ts

@@ -85,6 +85,26 @@ test("hostPlatformKey rejects unsupported platforms", () => {
 
 // --- resolveHostBinary error path: gtk on macOS, installed (not a checkout) ---
 
+test("ND_HOST_BINARY wins over resolution, and a missing path errors", async () => {
+  const self = resolve(import.meta.dir, "index.test.ts");
+  const prev = process.env.ND_HOST_BINARY;
+  try {
+    process.env.ND_HOST_BINARY = self;
+    // gtk+darwin has no prebuilt and this packageDir is no checkout, so every
+    // other arm of the resolver would throw.
+    expect(
+      await resolveHostBinary({ backend: "gtk", platform: "darwin", arch: "arm64", packageDir: "/tmp/not-a-checkout/node_modules/@nativedesktop/host" }),
+    ).toBe(self);
+
+    process.env.ND_HOST_BINARY = "/tmp/no-such-nd-host-binary";
+    const err = await resolveHostBinary({ backend: "gtk", platform: "linux", arch: "x64" }).catch((e: Error) => e);
+    expect((err as Error).message).toContain("ND_HOST_BINARY");
+  } finally {
+    if (prev === undefined) delete process.env.ND_HOST_BINARY;
+    else process.env.ND_HOST_BINARY = prev;
+  }
+});
+
 test("gtk on darwin outside a source checkout states the three real options", async () => {
   // packageDir has no build.zig/swift two levels up, so isSourceCheckout is
   // false -- the shape of an installed copy inside some other project's

package/src/index.ts

@@ -6,6 +6,10 @@
 // ND_BACKEND env var.
 //
 // How binaries get resolved:
+//   - ND_HOST_BINARY: an explicit path, ahead of everything else. For hosts
+//     where no prebuilt can run (NixOS rejects generic dynamically linked
+//     executables) or none ships (gtk on macOS), pointing at a source-built
+//     binary is the only way through `nd dev`, which resolves its own host.
 //   - published install: the binary ships in a per-platform package
 //     (@nativedesktop/host-darwin-arm64, @nativedesktop/host-linux-x64) listed
 //     as optionalDependencies of this package, the Electron/esbuild model. npm
@@ -133,6 +137,7 @@ function isSourceCheckout(repoRoot: string): boolean {
 /**
  * Absolute path to the host binary for the requested backend, building it on
  * first run when inside a source checkout. Resolution order per backend:
+ *   0. ND_HOST_BINARY, an explicit path that wins outright
  *   1. prebuilt binary from the installed @nativedesktop/host-<os>-<arch> package
  *   2. (source checkout only) freshly built zig-out / swift .build artifacts
  *   3. (source checkout only) build the backend, then return the built artifact
@@ -142,6 +147,13 @@ function isSourceCheckout(repoRoot: string): boolean {
 export async function resolveHostBinary(
   opts: { backend?: Backend; platform?: string; arch?: string; packageDir?: string } = {},
 ): Promise<string> {
+  const explicit = process.env.ND_HOST_BINARY;
+  if (explicit) {
+    if (!existsSync(explicit)) {
+      throw new Error(`@nativedesktop/host: ND_HOST_BINARY points at "${explicit}", which does not exist`);
+    }
+    return resolve(explicit);
+  }
   const backend = resolveBackend(opts);
   const { packageName, binaryName, repoRoot, fresh } = hostBinaryCandidates(backend, opts);
   const prebuilt = prebuiltHostBinary(backend);
@@ -175,14 +187,15 @@ export async function resolveHostBinary(
       `@nativedesktop/host: no gtk host binary for "${key}". The gtk backend ships no macOS prebuilt ` +
         `by design (it links Homebrew paths). Either build one from a NativeDesktop source checkout ` +
         `(${backendBuildHint(backend)}), or pass an explicit binary path instead of resolving one ` +
-        `(e.g. launchApp({ hostBinary }) in @nativedesktop/test).`,
+        `(ND_HOST_BINARY=<path>, or launchApp({ hostBinary }) in @nativedesktop/test).`,
     );
   }
   const hint = packageName
     ? `Expected ${packageName}/bin/${binaryName} (an optionalDependency of @nativedesktop/host); ` +
       `reinstall without --no-optional, or build in a NativeDesktop checkout (${backendBuildHint(backend)}).`
     : `No prebuilt package exists for this target; supported targets are darwin-arm64 (appkit) and ` +
-      `linux-x64 (gtk). Build in a NativeDesktop checkout (${backendBuildHint(backend)}).`;
+      `linux-x64 (gtk). Build in a NativeDesktop checkout (${backendBuildHint(backend)}) and point ` +
+      `ND_HOST_BINARY at it.`;
   throw new Error(`@nativedesktop/host: no ${backend} host binary for "${key}". ${hint}`);
 }