@relayfile/sdk 0.8.19 → 0.8.20

package/dist/mount-launcher.js

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
-import { constants as fsConstants, createWriteStream } from "node:fs";
-import { access, mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { createWriteStream } from "node:fs";
+import { mkdir, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
-import { fileURLToPath } from "node:url";
 import { RelayFileClient } from "./client.js";
+import { getRelayfileMountBinaryPath } from "./mount-path.js";
 import { CloudAbortError, MountModeUnavailableError, MountReadyTimeoutError, RelayfileSetupError } from "./setup-errors.js";
 const DEFAULT_READY_POLL_INTERVAL_MS = 250;
 const DEFAULT_STOP_TIMEOUT_MS = 10_000;
@@ -295,43 +295,11 @@ function normalizeNonEmptyString(value) {
     return typeof value === "string" && value.trim() !== "" ? value : undefined;
 }
 async function resolveRelayfileMountCommand() {
-    const executableFromPath = await findExecutableInPath("relayfile-mount");
-    if (executableFromPath) {
-        return executableFromPath;
-    }
-    const candidates = [
-        process.env.RELAYFILE_MOUNT_BIN,
-        fileURLToPath(new URL("../../../../bin/relayfile-mount", import.meta.url))
-    ];
-    for (const candidate of candidates) {
-        if (!candidate) {
-            continue;
-        }
-        if (await isExecutable(candidate)) {
-            return candidate;
-        }
-    }
-    return "relayfile-mount";
-}
-async function findExecutableInPath(command) {
-    const pathValue = process.env.PATH ?? "";
-    const pathEntries = pathValue.split(path.delimiter).filter(Boolean);
-    for (const entry of pathEntries) {
-        const candidate = path.join(entry, command);
-        if (await isExecutable(candidate)) {
-            return candidate;
-        }
-    }
-    return null;
-}
-async function isExecutable(candidate) {
-    try {
-        await access(candidate, fsConstants.X_OK);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    // Delegates to the shared resolver, which checks the RELAYFILE_MOUNT_BIN
+    // override, local source-checkout builds, the platform-specific optional-dep
+    // package (@relayfile/mount-<platform>-<arch>), then PATH. Falls back to the
+    // bare command name so spawn surfaces a clear ENOENT if nothing is found.
+    return getRelayfileMountBinaryPath() ?? "relayfile-mount";
 }
 async function rotateMountLogIfNeeded(logPath) {
     try {

package/dist/mount-path.d.ts

@@ -0,0 +1,18 @@
+export declare function getOptionalDepPackageName(platform?: string, arch?: string): string;
+/**
+ * Resolve the relayfile-mount binary path.
+ *
+ * Search order:
+ *   1. Explicit env override (RELAYFILE_MOUNT_BIN)
+ *   2. Local source-checkout build (bin/ or dist/), when loaded from a checkout
+ *   3. Platform-specific optional-dep package — primary production path
+ *   4. PATH lookup
+ *
+ * @returns Absolute path to the binary, or null if none is found.
+ */
+export declare function getRelayfileMountBinaryPath(): string | null;
+/**
+ * Human-readable error explaining that the optional-dep package for the
+ * current platform/arch isn't installed.
+ */
+export declare function formatMountNotFoundError(): string;

package/dist/mount-path.js

@@ -0,0 +1,179 @@
+/**
+ * Resolves the relayfile-mount binary path at runtime.
+ *
+ * Mirrors the agent-relay broker resolver (`@agent-relay/harness-driver`'s
+ * broker-path): the binary ships as platform-specific optional-dependency
+ * packages (`@relayfile/mount-<platform>-<arch>`) that npm installs only for
+ * the matching os/cpu, and the SDK locates the right one via `require.resolve`.
+ * No postinstall download is involved.
+ *
+ * Usage:
+ *   import { getRelayfileMountBinaryPath } from "@relayfile/sdk/mount-path"
+ *   const binPath = getRelayfileMountBinaryPath()
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const MOUNT_BIN = "relayfile-mount";
+/**
+ * Node's `process.arch` ("x64"/"arm64") differs from Go's GOARCH
+ * ("amd64"/"arm64"). The optional-dep package name follows Node's convention
+ * (matching the broker packages); the source-checkout `dist/` file names follow
+ * Go's. This maps Node arch -> Go arch for dev resolution.
+ */
+function goArch(arch = process.arch) {
+    return arch === "x64" ? "amd64" : arch;
+}
+export function getOptionalDepPackageName(platform = process.platform, arch = process.arch) {
+    return `@relayfile/mount-${platform}-${arch}`;
+}
+function getCurrentModuleDir() {
+    try {
+        return dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return null;
+    }
+}
+function addUnique(paths, candidate) {
+    if (candidate && !paths.includes(candidate)) {
+        paths.push(candidate);
+    }
+}
+/**
+ * Anchors from which to run `require.resolve` for the optional-dep package.
+ * Covers the SDK's own location, the entry script (CLI consumers / bundled
+ * installs where the SDK lives under the consumer's node_modules), and the
+ * consumer's cwd.
+ */
+function getResolutionReferences() {
+    const refs = [];
+    const moduleDir = getCurrentModuleDir();
+    addUnique(refs, moduleDir ? join(moduleDir, "mount-path.js") : null);
+    if (process.argv[1]) {
+        addUnique(refs, process.argv[1]);
+    }
+    addUnique(refs, join(process.cwd(), "package.json"));
+    return refs;
+}
+/**
+ * Resolve the binary via the platform-specific optional-dependency package.
+ * Returns null when the optional dep is not installed (expected under
+ * --omit=optional, or before the package has been published for a platform).
+ */
+function getOptionalDepBinaryPath() {
+    const pkgName = getOptionalDepPackageName();
+    for (const ref of getResolutionReferences()) {
+        try {
+            const pkgJsonPath = createRequire(ref).resolve(`${pkgName}/package.json`);
+            const binPath = join(dirname(pkgJsonPath), "bin", MOUNT_BIN);
+            if (existsSync(binPath)) {
+                return binPath;
+            }
+        }
+        catch {
+            // Try the next reference.
+        }
+    }
+    return null;
+}
+function isSourceCheckoutRoot(candidate) {
+    const root = resolve(candidate);
+    return (existsSync(join(root, "go.mod")) &&
+        existsSync(join(root, "cmd", "relayfile-mount", "main.go")));
+}
+function findAncestorSourceCheckoutRoot(start) {
+    let current = resolve(start);
+    for (let i = 0; i < 8; i += 1) {
+        if (isSourceCheckoutRoot(current)) {
+            return current;
+        }
+        const parent = resolve(current, "..");
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Local `make build`/`make build-all` outputs, used when the SDK is loaded
+ * from a relayfile source checkout.
+ */
+function getSourceCheckoutBinaryPaths() {
+    const paths = [];
+    const roots = new Set();
+    const addRoot = (candidate) => {
+        if (!candidate) {
+            return;
+        }
+        const root = resolve(candidate);
+        if (!isSourceCheckoutRoot(root) || roots.has(root)) {
+            return;
+        }
+        roots.add(root);
+        addUnique(paths, join(root, "bin", MOUNT_BIN));
+        addUnique(paths, join(root, "dist", `relayfile-mount-${process.platform}-${goArch()}`));
+    };
+    addRoot(findAncestorSourceCheckoutRoot(process.cwd()));
+    const moduleDir = getCurrentModuleDir();
+    if (moduleDir) {
+        // packages/sdk/typescript/dist -> repo root is four levels up.
+        addRoot(findAncestorSourceCheckoutRoot(moduleDir));
+    }
+    return paths;
+}
+function findExecutableInPath() {
+    const ext = process.platform === "win32" ? ".exe" : "";
+    const entries = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    for (const entry of entries) {
+        const candidate = join(entry, `${MOUNT_BIN}${ext}`);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the relayfile-mount binary path.
+ *
+ * Search order:
+ *   1. Explicit env override (RELAYFILE_MOUNT_BIN)
+ *   2. Local source-checkout build (bin/ or dist/), when loaded from a checkout
+ *   3. Platform-specific optional-dep package — primary production path
+ *   4. PATH lookup
+ *
+ * @returns Absolute path to the binary, or null if none is found.
+ */
+export function getRelayfileMountBinaryPath() {
+    const override = process.env.RELAYFILE_MOUNT_BIN;
+    if (override) {
+        const resolved = resolve(override);
+        if (existsSync(resolved)) {
+            return resolved;
+        }
+    }
+    for (const sourcePath of getSourceCheckoutBinaryPaths()) {
+        if (existsSync(sourcePath)) {
+            return sourcePath;
+        }
+    }
+    const optionalDepBinary = getOptionalDepBinaryPath();
+    if (optionalDepBinary) {
+        return optionalDepBinary;
+    }
+    return findExecutableInPath();
+}
+/**
+ * Human-readable error explaining that the optional-dep package for the
+ * current platform/arch isn't installed.
+ */
+export function formatMountNotFoundError() {
+    const pkgName = getOptionalDepPackageName();
+    return (`relayfile couldn't find a relayfile-mount binary for ` +
+        `${process.platform}-${process.arch}. The optional dependency ${pkgName} ` +
+        `is expected to be installed alongside @relayfile/sdk. Try reinstalling ` +
+        `with --include=optional, or set RELAYFILE_MOUNT_BIN to a binary you've ` +
+        `built or downloaded manually.`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayfile/sdk",
-  "version": "0.8.19",
+  "version": "0.8.20",
   "description": "TypeScript SDK for relayfile — real-time filesystem for humans and agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,10 @@
       "types": "./dist/mount-harness.d.ts",
       "default": "./dist/mount-harness.js"
     },
+    "./mount-path": {
+      "types": "./dist/mount-path.d.ts",
+      "default": "./dist/mount-path.js"
+    },
     "./workspace-seeder": {
       "types": "./dist/workspace-seeder.d.ts",
       "default": "./dist/workspace-seeder.js"
@@ -55,10 +59,16 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@relayfile/core": "0.8.19",
+    "@relayfile/core": "0.8.20",
     "ignore": "^7.0.5",
     "tar": "^7.5.10"
   },
+  "optionalDependencies": {
+    "@relayfile/mount-darwin-arm64": "0.8.20",
+    "@relayfile/mount-darwin-x64": "0.8.20",
+    "@relayfile/mount-linux-arm64": "0.8.20",
+    "@relayfile/mount-linux-x64": "0.8.20"
+  },
   "peerDependencies": {},
   "devDependencies": {
     "typescript": "^5.7.3",