@nativedesktop/host 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativedesktop/host",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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.1.2",
+    "@nativedesktop/host-linux-x64": "0.1.2"
+  }
 }

package/src/index.test.ts

@@ -3,7 +3,7 @@
 // layout. Run with: bun test packages/host/
 import { test, expect } from "bun:test";
 import { resolve } from "node:path";
-import { hostBinaryCandidates, hostPackageName, hostPlatformKey, resolveBackend } from "./index.ts";
+import { hostBinaryCandidates, hostPackageName, hostPlatformKey, resolveBackend, resolveHostBinary } from "./index.ts";
 
 // --- backend selection: platform × env × flag ------------------------------
 
@@ -82,3 +82,40 @@ test("hostPlatformKey rejects unsupported platforms", () => {
   expect(hostPlatformKey("darwin", "arm64")).toBe("darwin-arm64");
   expect(() => hostPlatformKey("sunos", "arm64")).toThrow(/unsupported platform/);
 });
+
+// --- 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
+  // node_modules (packageName is already undefined for gtk+darwin regardless
+  // of packageDir, since PLATFORM_PACKAGES has no entry for it).
+  const err = await resolveHostBinary({ backend: "gtk", platform: "darwin", arch: "arm64", packageDir: "/tmp/not-a-checkout/node_modules/@nativedesktop/host" }).catch(
+    (e: Error) => e,
+  );
+  expect(err).toBeInstanceOf(Error);
+  const message = (err as Error).message;
+  expect(message).toContain("by design");
+  expect(message).toContain("source checkout");
+  expect(message).toContain("explicit binary path");
+});

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,15 +137,25 @@ 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
  * Outside a checkout with no prebuilt, throws naming the missing platform
  * package (or the supported target list when none exists for this machine).
  */
-export async function resolveHostBinary(opts: { backend?: Backend } = {}): Promise<string> {
+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);
+  const { packageName, binaryName, repoRoot, fresh } = hostBinaryCandidates(backend, opts);
   const prebuilt = prebuiltHostBinary(backend);
   const source = isSourceCheckout(repoRoot);
 
@@ -163,12 +177,26 @@ export async function resolveHostBinary(opts: { backend?: Backend } = {}): Promi
     return buildBackend(backend, repoRoot, fresh);
   }
 
+  const key = hostPlatformKey(opts.platform, opts.arch);
+  // gtk-on-macOS is the one combination that will never get a package entry
+  // (see PLATFORM_PACKAGES above), so the generic "unsupported target" hint
+  // below reads as a dead end instead of the three real ways forward. State
+  // them explicitly: this is by design, not missing packaging.
+  if (!packageName && backend === "gtk" && key.startsWith("darwin-")) {
+    throw new Error(
+      `@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 ` +
+        `(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)}).`;
-  throw new Error(`@nativedesktop/host: no ${backend} host binary for "${hostPlatformKey()}". ${hint}`);
+      `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}`);
 }
 
 function backendBuildHint(backend: Backend): string {