@relayfile/sdk 0.10.62 → 0.10.64

package/dist/relay-cli/index.d.ts

@@ -0,0 +1,125 @@
+/**
+ * relayfile's CLI surface, mounted by the `agent-relay` CLI as
+ * `agent-relay file`.
+ *
+ * The surface does not reimplement any relayfile command. `commands` is a
+ * checked-in snapshot of the Go binary's own command table (emitted by
+ * `relayfile __command-spec --json`, regenerated by `npm run gen:command-spec`)
+ * and `run` spawns that same binary, so `agent-relay file <cmd>` and
+ * `relayfile <cmd>` are the same code path.
+ *
+ * Structurally typed against `@agent-relay/cli-surface` (a devDependency):
+ * this package gains no runtime dependency on relay.
+ */
+import { type EnsureCloudSession } from "./cloud-preflight.js";
+import { type ResolveRelayfileBinaryOptions } from "./resolve-binary.js";
+/** Contract revision implemented here; mirrors `@agent-relay/cli-surface`. */
+export declare const RELAY_CLI_CONTRACT_VERSION = 1;
+/** Exit code for an argv the surface cannot route. */
+export declare const RELAY_CLI_EXIT_UNKNOWN_COMMAND = 2;
+/**
+ * Exit code when no relayfile binary could be found. Distinct from an
+ * unroutable argv (2) and from any code the binary itself returns, so a host
+ * can tell "relayfile is not installed here" from "relayfile ran and failed".
+ */
+export declare const RELAY_CLI_EXIT_BINARY_NOT_FOUND = 127;
+/**
+ * Output sink supplied by the host.
+ *
+ * Chunks are handed over as the raw bytes the binary wrote, not as decoded
+ * strings. `relayfile export --format tar --output -` streams a tar archive to
+ * stdout, and decoding that as UTF-8 corrupts it silently; a multibyte
+ * character split across two reads corrupts the same way in the other
+ * direction. Passing the bytes through untouched is correct for both, and
+ * matches `RelayCliIo` in `@agent-relay/cli-surface`.
+ */
+export interface RelayCliIo {
+    stdout(chunk: string | Uint8Array): void;
+    stderr(chunk: string | Uint8Array): void;
+}
+export interface RelayCliArgSpec {
+    name: string;
+    description: string;
+    required: boolean;
+    variadic?: boolean;
+}
+export interface RelayCliOptionSpec {
+    flags: string;
+    description: string;
+    defaultValue?: string | boolean | number;
+}
+export interface RelayCliCommandSpec {
+    name: string;
+    description: string;
+    aliases?: readonly string[];
+    args?: readonly RelayCliArgSpec[];
+    options?: readonly RelayCliOptionSpec[];
+    subcommands?: readonly RelayCliCommandSpec[];
+    deprecated?: {
+        replacement: string;
+        since?: string;
+    };
+    hidden?: boolean;
+}
+export interface RelayCliSurface {
+    id: string;
+    version: string;
+    contract: 1;
+    commands: readonly RelayCliCommandSpec[];
+    run(argv: readonly string[], io: RelayCliIo): Promise<number>;
+}
+export interface CreateRelayCliSurfaceOptions {
+    /** Binary lookup overrides; forwarded to `resolveRelayfileBinary`. */
+    resolve?: ResolveRelayfileBinaryOptions;
+    /** Environment for the child process and the Cloud preflight. */
+    env?: NodeJS.ProcessEnv;
+    /** Working directory for the child process. */
+    cwd?: string;
+    /**
+     * Skip the Cloud sign-in preflight. Only for tests: skipping it makes
+     * `agent-relay file setup` behave differently from `relayfile setup`.
+     */
+    skipCloudPreflight?: boolean;
+    /** Injected Cloud SDK entry point, for tests. */
+    ensureCloudSession?: EnsureCloudSession;
+}
+/**
+ * Path of the checked-in command-tree snapshot.
+ *
+ * Lives next to the compiled module so the published package carries it.
+ */
+export declare const COMMAND_SPEC_PATH: string;
+/**
+ * Read the snapshot of the Go binary's command tree.
+ *
+ * Read from disk rather than imported so the module needs no JSON import
+ * attributes and stays loadable from both ESM and a CJS `import()`.
+ *
+ * @returns The command tree the relayfile binary dispatches.
+ */
+export declare function relayfileCommands(): readonly RelayCliCommandSpec[];
+/**
+ * Every name and alias the relayfile binary routes at the top level.
+ *
+ * Includes three tokens the binary routes outside its command table, and so
+ * keeps out of its published surface: `help` (the host renders help itself),
+ * `__command-spec` (the introspection hook that produces the snapshot), and
+ * `version` (handled by the binary's `wantsVersion`, the same path as
+ * `--version`). They are routable here but deliberately not declared in
+ * `commands`: that tree is a generated snapshot of the Go command table, and
+ * the binary's own usage does not advertise `version` either, so declaring it
+ * would make `agent-relay file --help` claim a command `relayfile --help`
+ * does not.
+ *
+ * @returns The routable top-level tokens.
+ */
+export declare function routableTopLevelNames(): readonly string[];
+/**
+ * Create relayfile's mountable CLI surface.
+ *
+ * @param options - Optional overrides for binary lookup, env, and cwd.
+ * @returns A surface satisfying `@agent-relay/cli-surface`'s `RelayCliSurface`.
+ */
+export declare function createRelayCliSurface(options?: CreateRelayCliSurfaceOptions): RelayCliSurface;
+export { buildGoRunBinary, goRunBinaryPath, GoBuildFailedError, GoToolchainMissingError, RelayfileBinaryNotFoundError, resolveRelayfileBinary, findSourceCheckoutRoot, formatBinaryNotFoundMessage, genericBinaryName, platformBinaryName, platformPackageBinaryName, platformPackageName, platformPackageNames, GO_TOOLCHAIN_MISSING_MESSAGE, RELAYFILE_CLI_BIN_ENV, type BuildGoRunBinaryOptions, type RelayfileBinaryResolution, type RelayfileGoRunResolution, type ResolveRelayfileBinaryOptions } from "./resolve-binary.js";
+export { announceSetupIntent, hasValidSetupArguments, parseGoDurationMilliseconds, parseSetupArguments, prepareCloudSession, shouldPrepareCloudSession, loadCloudSessionSDK, DEFAULT_CLOUD_API_URL, SETUP_INTENT, SETUP_INTENT_PRINTED_ENV, type CloudPreflightOptions, type EnsureCloudSession } from "./cloud-preflight.js";

package/dist/relay-cli/index.js

@@ -0,0 +1,197 @@
+/**
+ * relayfile's CLI surface, mounted by the `agent-relay` CLI as
+ * `agent-relay file`.
+ *
+ * The surface does not reimplement any relayfile command. `commands` is a
+ * checked-in snapshot of the Go binary's own command table (emitted by
+ * `relayfile __command-spec --json`, regenerated by `npm run gen:command-spec`)
+ * and `run` spawns that same binary, so `agent-relay file <cmd>` and
+ * `relayfile <cmd>` are the same code path.
+ *
+ * Structurally typed against `@agent-relay/cli-surface` (a devDependency):
+ * this package gains no runtime dependency on relay.
+ */
+import { spawn } from "node:child_process";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RELAYFILE_VERSION } from "../package-version.js";
+import { announceSetupIntent, prepareCloudSession } from "./cloud-preflight.js";
+import { buildGoRunBinary, GoBuildFailedError, GoToolchainMissingError, RelayfileBinaryNotFoundError, resolveRelayfileBinary } from "./resolve-binary.js";
+/** Contract revision implemented here; mirrors `@agent-relay/cli-surface`. */
+export const RELAY_CLI_CONTRACT_VERSION = 1;
+/** Exit code for an argv the surface cannot route. */
+export const RELAY_CLI_EXIT_UNKNOWN_COMMAND = 2;
+/**
+ * Exit code when no relayfile binary could be found. Distinct from an
+ * unroutable argv (2) and from any code the binary itself returns, so a host
+ * can tell "relayfile is not installed here" from "relayfile ran and failed".
+ */
+export const RELAY_CLI_EXIT_BINARY_NOT_FOUND = 127;
+/**
+ * Path of the checked-in command-tree snapshot.
+ *
+ * Lives next to the compiled module so the published package carries it.
+ */
+export const COMMAND_SPEC_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "command-spec.json");
+let cachedCommands;
+/**
+ * Read the snapshot of the Go binary's command tree.
+ *
+ * Read from disk rather than imported so the module needs no JSON import
+ * attributes and stays loadable from both ESM and a CJS `import()`.
+ *
+ * @returns The command tree the relayfile binary dispatches.
+ */
+export function relayfileCommands() {
+    if (!cachedCommands) {
+        cachedCommands = JSON.parse(readFileSync(COMMAND_SPEC_PATH, "utf8"));
+    }
+    return cachedCommands;
+}
+/**
+ * Every name and alias the relayfile binary routes at the top level.
+ *
+ * Includes three tokens the binary routes outside its command table, and so
+ * keeps out of its published surface: `help` (the host renders help itself),
+ * `__command-spec` (the introspection hook that produces the snapshot), and
+ * `version` (handled by the binary's `wantsVersion`, the same path as
+ * `--version`). They are routable here but deliberately not declared in
+ * `commands`: that tree is a generated snapshot of the Go command table, and
+ * the binary's own usage does not advertise `version` either, so declaring it
+ * would make `agent-relay file --help` claim a command `relayfile --help`
+ * does not.
+ *
+ * @returns The routable top-level tokens.
+ */
+export function routableTopLevelNames() {
+    const names = new Set(["help", "__command-spec", "version"]);
+    for (const command of relayfileCommands()) {
+        names.add(command.name);
+        for (const alias of command.aliases ?? []) {
+            names.add(alias);
+        }
+    }
+    return [...names];
+}
+function isFlag(token) {
+    return token.startsWith("-");
+}
+/**
+ * Exit code convention for a child killed by a signal: 128 + signal number, so
+ * callers can tell user cancellation (130 for SIGINT) from a generic failure.
+ *
+ * @returns The exit code to report for `signal`.
+ */
+function exitCodeForSignal(signal) {
+    const signum = os.constants.signals[signal];
+    return typeof signum === "number" ? 128 + signum : 1;
+}
+/**
+ * Create relayfile's mountable CLI surface.
+ *
+ * @param options - Optional overrides for binary lookup, env, and cwd.
+ * @returns A surface satisfying `@agent-relay/cli-surface`'s `RelayCliSurface`.
+ */
+export function createRelayCliSurface(options = {}) {
+    const commands = relayfileCommands();
+    return {
+        id: "relayfile",
+        version: RELAYFILE_VERSION,
+        contract: RELAY_CLI_CONTRACT_VERSION,
+        commands,
+        async run(argv, io) {
+            const args = [...argv];
+            const env = options.env ?? process.env;
+            const first = args[0];
+            if (first !== undefined && !isFlag(first) && !routableTopLevelNames().includes(first)) {
+                io.stderr(`unknown command "${first}"\n`);
+                io.stderr(`run \`agent-relay file --help\` for the relayfile command tree\n`);
+                return RELAY_CLI_EXIT_UNKNOWN_COMMAND;
+            }
+            if (!options.skipCloudPreflight) {
+                // Agent Relay's Cloud SDK owns interactive login, token refresh,
+                // locking, and the canonical session store; the native runtime reads
+                // that same store directly. Running this here keeps
+                // `agent-relay file setup` identical to `relayfile setup`.
+                announceSetupIntent(args, env, (line) => io.stdout(`${line}\n`));
+                await prepareCloudSession(args, {
+                    env,
+                    writeLine: (line) => io.stdout(`${line}\n`),
+                    ensureCloudSession: options.ensureCloudSession
+                });
+            }
+            let resolution;
+            try {
+                resolution = resolveRelayfileBinary(options.resolve);
+            }
+            catch (error) {
+                if (!(error instanceof RelayfileBinaryNotFoundError)) {
+                    throw error;
+                }
+                // The contract says run() resolves to an exit code, so a missing
+                // binary is reported through io rather than thrown at the host. The
+                // message names the `@relayfile/cli-*` package to install for this
+                // platform; a bare ENOENT would send people hunting their PATH.
+                io.stderr(`${error.message}\n`);
+                return RELAY_CLI_EXIT_BINARY_NOT_FOUND;
+            }
+            let command = resolution.command;
+            let childArgs = [...resolution.args, ...args];
+            if (resolution.kind === "go-run") {
+                // `go run` would launch relayfile with the checkout as its working
+                // directory — `go` only finds the module from there — so every
+                // relative path in argv would resolve against the repository instead
+                // of wherever the caller ran. Build first, then spawn the result from
+                // the caller's directory.
+                try {
+                    command = buildGoRunBinary(resolution, { env });
+                    childArgs = [...args];
+                }
+                catch (error) {
+                    if (error instanceof GoToolchainMissingError ||
+                        error instanceof GoBuildFailedError) {
+                        io.stderr(`${error.message}\n`);
+                        return 1;
+                    }
+                    throw error;
+                }
+            }
+            const cwd = options.cwd;
+            return await new Promise((resolve, reject) => {
+                // stdin is inherited so interactive prompts (setup, login, delete
+                // confirmations) still work; stdout/stderr are piped into `io` because
+                // the contract forbids writing to the host's streams directly. No
+                // signal handlers are installed: the host owns them.
+                const child = spawn(command, childArgs, {
+                    cwd,
+                    env,
+                    stdio: ["inherit", "pipe", "pipe"]
+                });
+                // No setEncoding: the bytes go to `io` exactly as the binary wrote
+                // them. `export --format tar --output -` streams an archive here.
+                child.stdout?.on("data", (chunk) => io.stdout(chunk));
+                child.stderr?.on("data", (chunk) => io.stderr(chunk));
+                // A missing Go toolchain is reported by buildGoRunBinary above, not
+                // here: by this point `command` is always a real binary.
+                child.on("error", (error) => {
+                    reject(error);
+                });
+                child.on("close", (code, signal) => {
+                    if (typeof code === "number") {
+                        resolve(code);
+                        return;
+                    }
+                    if (signal) {
+                        resolve(exitCodeForSignal(signal));
+                        return;
+                    }
+                    resolve(1);
+                });
+            });
+        }
+    };
+}
+export { buildGoRunBinary, goRunBinaryPath, GoBuildFailedError, GoToolchainMissingError, RelayfileBinaryNotFoundError, resolveRelayfileBinary, findSourceCheckoutRoot, formatBinaryNotFoundMessage, genericBinaryName, platformBinaryName, platformPackageBinaryName, platformPackageName, platformPackageNames, GO_TOOLCHAIN_MISSING_MESSAGE, RELAYFILE_CLI_BIN_ENV } from "./resolve-binary.js";
+export { announceSetupIntent, hasValidSetupArguments, parseGoDurationMilliseconds, parseSetupArguments, prepareCloudSession, shouldPrepareCloudSession, loadCloudSessionSDK, DEFAULT_CLOUD_API_URL, SETUP_INTENT, SETUP_INTENT_PRINTED_ENV } from "./cloud-preflight.js";

package/dist/relay-cli/resolve-binary.d.ts

@@ -0,0 +1,220 @@
+/**
+ * The one implementation of "find the relayfile binary".
+ *
+ * The real relayfile CLI is the Go binary (`cmd/relayfile-cli`). Both entry
+ * points into it — the `relayfile` npm package's bin shim
+ * (`packages/cli/scripts/run.js`) and the `agent-relay file` CLI surface in
+ * this directory — resolve it through this module. Nothing else in the repo
+ * may reimplement the lookup.
+ *
+ * The binary reaches a machine two different ways, and the resolver has to
+ * cope with both:
+ *
+ *  - As `@relayfile/cli-<platform>-<arch>`, an optional dependency of this
+ *    package. npm installs only the one matching the host's `os`/`cpu`, so
+ *    nothing is downloaded at install time, the install works offline and in
+ *    CI, and integrity comes from the registry. This is the only path that
+ *    exists for a consumer that depends on `@relayfile/sdk` without depending
+ *    on `relayfile` — `agent-relay` is exactly that consumer.
+ *  - Inside the `relayfile` package's own `bin/`, put there by that package's
+ *    `postinstall` (`packages/cli/scripts/install.js`), which downloads the
+ *    per-platform build from GitHub Releases.
+ */
+/** Environment variable that pins the binary, bypassing every other step. */
+export declare const RELAYFILE_CLI_BIN_ENV = "RELAYFILE_CLI_BIN";
+/** How the resolver decided to launch relayfile. */
+export type RelayfileBinaryResolution = {
+    /** A packaged or locally built binary was found. */
+    kind: "binary";
+    command: string;
+    args: readonly string[];
+    /** Absolute path of the binary that matched. */
+    binaryPath: string;
+} | {
+    /**
+     * No binary was found, but we are inside a source checkout, so relayfile
+     * runs straight from Go source. `postinstall` intentionally skips
+     * building the binary in a checkout; without this fallback the installed
+     * `relayfile` command would be unusable there.
+     */
+    kind: "go-run";
+    command: "go";
+    args: readonly string[];
+    cwd: string;
+};
+export interface ResolveRelayfileBinaryOptions {
+    /**
+     * Directories to search for a packaged binary, highest priority first.
+     * Defaults to the `bin` directory of the installed `relayfile` package plus
+     * the workspace copy when running inside this repo.
+     */
+    binDirs?: readonly string[];
+    /** Extra directories to start the source-checkout search from. */
+    searchFrom?: readonly string[];
+    /**
+     * Anchors for the `require.resolve` that finds
+     * `@relayfile/cli-<platform>-<arch>`. Defaults to this module, the entry
+     * script, and the cwd — the three places a consumer's copy of the package
+     * can be reached from.
+     */
+    resolveFrom?: readonly string[];
+    /** `PATH` entries for the last-resort lookup. Defaults to `env.PATH`. */
+    pathEntries?: readonly string[];
+    /** Environment read for `RELAYFILE_CLI_BIN` and `PATH`. */
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    arch?: string;
+    /** Injected for tests. */
+    fileExists?: (candidate: string) => boolean;
+}
+/**
+ * Name of the npm package carrying the prebuilt binary for a target.
+ *
+ * @param platform - Node platform id; defaults to this host's.
+ * @param arch - Node arch id; defaults to this host's.
+ * @returns The package name, or null when no package is published for the
+ *   target (nothing to suggest installing, so callers say "build from source").
+ */
+export declare function platformPackageName(platform?: string, arch?: string): string | null;
+/** Every `@relayfile/cli-*` package name, for tests and release tooling. */
+export declare function platformPackageNames(): readonly string[];
+/**
+ * Name of the binary inside a `@relayfile/cli-*` package.
+ *
+ * It keeps the Go binary's own name (matching `relayfile-mount` inside the
+ * `@relayfile/mount-*` packages) rather than the `relayfile` name the CLI
+ * package installs, so the two never collide on a machine that has both.
+ *
+ * @param platform - Node platform id; defaults to this host's.
+ * @returns The file name, with `.exe` on Windows.
+ */
+export declare function platformPackageBinaryName(platform?: string): string;
+/** Thrown when neither a binary nor a usable source checkout was found. */
+export declare class RelayfileBinaryNotFoundError extends Error {
+    readonly platform: string;
+    readonly arch: string;
+    /** The `@relayfile/cli-*` package for this target, when one is published. */
+    readonly platformPackage: string | null;
+    constructor(platform: string, arch: string);
+}
+/**
+ * Explain what to install, for this exact platform.
+ *
+ * A bare ENOENT sends people looking for a bug in their PATH. The prebuilt
+ * binary is an optional dependency, so the two things that actually cause this
+ * — `--omit=optional` and an unsupported target — both need naming.
+ *
+ * @param platform - Node platform id.
+ * @param arch - Node arch id.
+ * @returns The message carried by `RelayfileBinaryNotFoundError`.
+ */
+export declare function formatBinaryNotFoundMessage(platform: string, arch: string): string;
+/**
+ * Name of the per-platform binary shipped inside the `relayfile` package.
+ *
+ * @returns The packaged binary's file name, or null on an unsupported target.
+ */
+export declare function platformBinaryName(platform?: string, arch?: string): string | null;
+/**
+ * Name of the binary the CLI package installs and runs, `bin/relayfile`.
+ *
+ * @param platform - Node platform id; defaults to this host's.
+ * @returns The file name, with `.exe` on Windows.
+ */
+export declare function genericBinaryName(platform?: string): string;
+/**
+ * Locate a relayfile source checkout: a directory with both `go.mod` and
+ * `cmd/relayfile-cli`.
+ *
+ * @returns The checkout root, or null when there is none above `start`.
+ */
+export declare function findSourceCheckoutRoot(start: string, exists?: (candidate: string) => boolean): string | null;
+/**
+ * Resolve how to launch the relayfile CLI on this machine.
+ *
+ * Search order, and why it is this order:
+ *  1. `RELAYFILE_CLI_BIN` — the escape hatch, so a developer or operator can
+ *     always pin an exact binary.
+ *  2. `@relayfile/cli-<platform>-<arch>` — the prebuilt binary npm installed
+ *     for this host. First because it is the only path that exists for a
+ *     consumer of `@relayfile/sdk` that does not also depend on `relayfile`
+ *     (`agent-relay file` is that consumer), and because it needs no network.
+ *  3. The `binDirs` chain: a generic `bin/relayfile` (the `relayfile`
+ *     package's postinstall download, or a local build), then the
+ *     per-platform `bin/relayfile-cli-<os>-<arch>` that package ships.
+ *  4. `make build` / `make release` outputs in an enclosing source checkout.
+ *  5. `go run ./cmd/relayfile-cli` from that checkout.
+ *  6. `PATH`, for a binary installed outside npm.
+ *
+ * @param options - Search overrides; all are optional.
+ * @returns The command, argv prefix, and cwd to spawn.
+ * @throws {RelayfileBinaryNotFoundError} When nothing usable was found.
+ */
+export declare function resolveRelayfileBinary(options?: ResolveRelayfileBinaryOptions): RelayfileBinaryResolution;
+/** Message shown when a source checkout was found but Go is not installed. */
+export declare const GO_TOOLCHAIN_MISSING_MESSAGE: string;
+/** A `go-run` resolution: no binary was found, but a checkout was. */
+export type RelayfileGoRunResolution = Extract<RelayfileBinaryResolution, {
+    kind: "go-run";
+}>;
+/** Thrown by `buildGoRunBinary` when there is no `go` on PATH. */
+export declare class GoToolchainMissingError extends Error {
+    constructor();
+}
+/** Thrown by `buildGoRunBinary` when `go build` itself fails. */
+export declare class GoBuildFailedError extends Error {
+    /** `go build`'s exit code, or null when it was killed by a signal. */
+    readonly exitCode: number | null;
+    constructor(exitCode: number | null, stderr: string);
+}
+export interface BuildGoRunBinaryOptions {
+    /** Environment for `go build`; also supplies the PATH it is found on. */
+    env?: NodeJS.ProcessEnv;
+    /** Output path override, for tests. */
+    outputPath?: string;
+}
+/**
+ * Where a source-checkout build is cached: outside the checkout, keyed by it.
+ *
+ * Not `<checkout>/bin`, which is `make build`'s output — a fallback launch
+ * must not write into someone's working tree, and a read-only checkout still
+ * has to work.
+ *
+ * @param checkout - The source checkout root.
+ * @param platform - Node platform id; defaults to this host's.
+ * @returns The absolute path to build to.
+ */
+export declare function goRunBinaryPath(checkout: string, platform?: string): string;
+/**
+ * Turn a `go-run` resolution into an executable binary.
+ *
+ * `go run` cannot be used directly, because the program it launches inherits
+ * the `go` command's own working directory — and `go` only finds the module
+ * from that directory, so it has to be the checkout. Every relative path in
+ * the caller's argv would then resolve against the repository instead of the
+ * directory the caller actually ran in (`--output report.json` writing into
+ * the checkout root). `go -C <checkout> run` has the same effect, and passing
+ * an absolute package path fails outright outside a module.
+ *
+ * Building first and spawning the result separates the two: the build runs in
+ * the checkout, where the module is, and the binary runs wherever the caller
+ * asked for. Go's build cache makes the repeat cost a relink.
+ *
+ * The build never writes the shared path directly. That path is keyed by the
+ * checkout alone, so every process that falls back to source aims at the same
+ * file — and a `listen` or `mount` launched from it keeps running for hours.
+ * Writing it in place would mean overwriting a binary that is executing
+ * (impossible on Windows, and on Unix a window in which a concurrent build has
+ * replaced it with a partial file). So `go build` writes a private sibling and
+ * the result is published with one rename: atomic on POSIX, and an already
+ * running process keeps the inode it started from. If the rename cannot
+ * happen — Windows refuses to replace a running `.exe` — the caller gets the
+ * private path instead, which is just as runnable.
+ *
+ * @param resolution - The `go-run` resolution to materialize.
+ * @param options - Environment and output overrides.
+ * @returns The absolute path of the built binary.
+ * @throws {GoToolchainMissingError} When `go` is not on PATH.
+ * @throws {GoBuildFailedError} When `go build` exits non-zero.
+ */
+export declare function buildGoRunBinary(resolution: RelayfileGoRunResolution, options?: BuildGoRunBinaryOptions): string;