@nativedesktop/host 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nativedesktop/host",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Resolves the prebuilt NativeDesktop host binary for the current platform",
   "type": "module",
   "license": "MIT",

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,20 @@ 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("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

@@ -139,9 +139,11 @@ function isSourceCheckout(repoRoot: string): boolean {
  * 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 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 +165,25 @@ 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 ` +
+        `(e.g. 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}`);
+  throw new Error(`@nativedesktop/host: no ${backend} host binary for "${key}". ${hint}`);
 }
 
 function backendBuildHint(backend: Backend): string {