/**
 * File-based local DWN discovery for CLI and native apps.
 *
 * When `electrobun-dwn` (or any local DWN server) starts, it writes a
 * well-known file (`~/.enbox/dwn.json`) containing the DWN endpoint URL
 * and the server PID. CLI tools and native apps read this file to discover
 * the local DWN without port probing.
 *
 * The filesystem operations are abstracted behind {@link DiscoveryFileFs}
 * so the module can be tested without touching the real filesystem, and
 * adapted to runtimes that provide different I/O primitives.
 *
 * @see https://github.com/enboxorg/enbox/issues/587
 * @module
 */
/**
 * The JSON shape persisted in the discovery file.
 *
 * @see https://identity.foundation/dwn-transport/#discovery-file
 */
export interface DwnDiscoveryRecord {
    /** Base URL of the running DWN server (e.g. `"http://127.0.0.1:55500"`). */
    endpoint: string;
    /** OS process ID of the DWN server. Used for liveness checking. */
    pid: number;
    /**
     * Transport capabilities advertised by the server (e.g. `["http", "ws"]`).
     * Optional per the DWN Transport Spec.
     */
    capabilities?: string[];
}
/**
 * Minimal filesystem interface required by {@link DwnDiscoveryFile}.
 *
 * Consumers can provide a custom implementation for testing or for
 * runtimes that do not expose Node-compatible `fs` and `os` modules.
 */
export interface DiscoveryFileFs {
    /** Read the file at `path` and return its UTF-8 contents, or `null` if not found. */
    readFile(path: string): Promise<string | null>;
    /** Write `contents` to the file at `path`, creating parent directories as needed. */
    writeFile(path: string, contents: string): Promise<void>;
    /** Delete the file at `path`. Must not throw if the file does not exist. */
    removeFile(path: string): Promise<void>;
    /** Return `true` if the process with the given PID is alive. */
    isProcessAlive(pid: number): boolean;
    /** Return the user's home directory (e.g. `/home/alice`). */
    homedir(): string;
}
/**
 * Creates a {@link DiscoveryFileFs} backed by Node.js / Bun built-in
 * modules. Returns `undefined` in environments where `node:fs/promises`
 * or `node:os` are not available (e.g. browsers).
 */
export declare function createNodeDiscoveryFileFs(): DiscoveryFileFs | undefined;
/**
 * Directory under the user's home where the discovery file lives.
 * Shared with the `electrobun-dwn` app and other Enbox tooling.
 */
export declare const DISCOVERY_DIR = ".enbox";
/** Filename of the discovery file. */
export declare const DISCOVERY_FILENAME = "dwn.json";
/**
 * Reads, writes, and validates the `~/.enbox/dwn.json` discovery file.
 *
 * This is the **file-based discovery channel** for CLI and native apps.
 * It is complementary to the `dwn://connect` browser redirect flow.
 *
 * @example Reading the discovery file
 * ```ts
 * const discoveryFile = new DwnDiscoveryFile();
 * const record = await discoveryFile.read();
 *
 * if (record) {
 *   console.log(`Local DWN at ${record.endpoint}`);
 * }
 * ```
 *
 * @example Writing the discovery file (from electrobun-dwn)
 * ```ts
 * const discoveryFile = new DwnDiscoveryFile();
 * await discoveryFile.write({
 *   endpoint : 'http://127.0.0.1:55557',
 *   pid      : process.pid,
 * });
 * ```
 */
export declare class DwnDiscoveryFile {
    private readonly _fs;
    private readonly _filePath;
    /**
     * @param fs - Filesystem adapter. Defaults to Node/Bun built-ins.
     * @param filePath - Override the discovery file path (mainly for testing).
     * @throws If no filesystem adapter is available (e.g. in a browser).
     */
    constructor(fs?: DiscoveryFileFs, filePath?: string);
    /** The absolute path of the discovery file. */
    get path(): string;
    /**
     * Read and validate the discovery file.
     *
     * Returns the parsed {@link DwnDiscoveryRecord} if:
     * 1. The file exists and contains valid JSON.
     * 2. The `endpoint` is a non-empty string.
     * 3. The `pid` is a positive integer whose process is still alive.
     *
     * Returns `undefined` in all other cases (missing file, parse error,
     * stale PID). Stale files are automatically removed.
     */
    read(): Promise<DwnDiscoveryRecord | undefined>;
    /**
     * Write the discovery file. Creates the `~/.enbox/` directory if needed.
     *
     * @param record - The endpoint and PID to persist.
     */
    write(record: DwnDiscoveryRecord): Promise<void>;
    /**
     * Remove the discovery file. Does not throw if the file is already gone.
     */
    remove(): Promise<void>;
}
//# sourceMappingURL=dwn-discovery-file.d.ts.map