/**
 * Shared Weft server connection resolution for the HTTP client and CLI commands.
 *
 * A single resolver backs every entry point so `WEFT_ADDR`, `WEFT_TOKEN`,
 * `~/.weft/config` profiles, the local run lockfile, and the development default
 * are interpreted identically whether you construct an {@link HttpClient} or run
 * `weft api`/`weft codegen`.
 *
 * Resolution order for the server address is explicit option, then `WEFT_ADDR`,
 * then the selected profile's `server`, then the run lockfile written by
 * `weft serve` (CLI only — see `includeRunLockfile`), then
 * `http://localhost:7233`. Token resolution prefers the explicit option, then
 * `WEFT_TOKEN`, then the profile token (with `env:` and `tokenEnv` indirection).
 * A profile token is only applied when neither an explicit `server` option nor
 * `WEFT_ADDR` redirected the request to a different destination.
 *
 * This module is imported from `@lostgradient/weft/client` (browser-reachable),
 * so it must stay statically free of `node:*` and Bun-only imports. Environment
 * variables go through {@link readEnvironmentVariable}; `~/.weft/config` and the
 * run lockfile are read through {@link tryLoadNodeBuiltin}, which resolves
 * `node:fs`/`node:fs/promises` via `process.getBuiltinModule` instead of a
 * static import. Both return `undefined` outside Bun/Node, so a browser caller
 * that supplies explicit `server`/`token` never touches either.
 *
 * @module connection
 */
/**
 * Inputs accepted by {@link resolveConnection}.
 *
 * @example
 * ```ts
 * import { resolveConnection, type ConnectionOptions } from '@lostgradient/weft';
 *
 * const options: ConnectionOptions = {
 *   server: 'https://weft.example.com',
 *   token: 'secret-token',
 * };
 *
 * const connection = resolveConnection(options);
 * console.log(connection.server.toString());
 * ```
 */
export type ConnectionOptions = {
    readonly server?: string;
    readonly token?: string;
    readonly profile?: string;
    /**
     * Consult the local run lockfile written by `weft serve` as a fallback server
     * address. Defaults to `true` for CLI developer convenience; library clients
     * pass `false` so resolution stays explicit-options/env/profile/default.
     */
    readonly includeRunLockfile?: boolean;
};
/**
 * Resolved Weft server connection settings.
 *
 * @example
 * ```ts
 * import { resolveConnection, type ResolvedConnection } from '@lostgradient/weft';
 *
 * const connection: ResolvedConnection = resolveConnection({
 *   server: 'https://weft.example.com',
 *   token: 'secret-token',
 * });
 *
 * console.log(connection.token);
 * ```
 */
export type ResolvedConnection = {
    readonly server: URL;
    readonly token?: string;
};
/**
 * Default local Weft server address used when nothing else resolves.
 *
 * @example
 * ```ts
 * import { DEFAULT_WEFT_ADDRESS } from '@lostgradient/weft';
 *
 * console.log(DEFAULT_WEFT_ADDRESS); // "http://localhost:7233"
 * ```
 */
export declare const DEFAULT_WEFT_ADDRESS = "http://localhost:7233";
/**
 * Raised when connection resolution fails. Two cases surface as this error:
 * a present `~/.weft/config` file that cannot be parsed (a missing file is not
 * an error), and a resolved server value that is not a valid URL — regardless
 * of where it came from (`--server`/explicit option, `WEFT_ADDR`, the profile
 * `server` field, or the run lockfile). Both are surfaced rather than silently
 * connecting to the wrong server; the message carries the offending value (the
 * invalid URL string, or the config path for a parse failure).
 *
 * @example
 * ```ts
 * import { ConnectionConfigurationError, resolveConnection } from '@lostgradient/weft';
 *
 * try {
 *   resolveConnection();
 * } catch (error) {
 *   if (error instanceof ConnectionConfigurationError) {
 *     console.error(error.message);
 *   }
 * }
 * ```
 */
export declare class ConnectionConfigurationError extends Error {
    constructor(message: string);
}
/**
 * Resolve Weft server connection settings from explicit options, environment
 * variables, `~/.weft/config`, the local run lockfile (when
 * `includeRunLockfile` is not `false`), and the development default.
 *
 * Resolution is synchronous so it can run inside the {@link HttpClient}
 * constructor and CLI command handlers alike.
 *
 * @example
 * ```ts
 * import { resolveConnection } from '@lostgradient/weft';
 *
 * const connection = resolveConnection({ server: 'https://weft.example.com' });
 * console.log(connection.server.toString()); // "https://weft.example.com/"
 * ```
 */
export declare function resolveConnection(options?: ConnectionOptions): ResolvedConnection;
/** Record the address of a running server so later CLI commands can find it. */
export declare function writeRunLockfile(server: string): Promise<void>;
/** Remove the run lockfile when the recorded server shuts down. */
export declare function removeRunLockfile(server: string): Promise<void>;