import { FsInfo, FsDirectoryEntry, FsMkdirOptions, FsChange, Subscription, FsPickOptions, FsPickResult, FsReadOptions, FsReadResult, FsMetadata, FsWatchOptions, FsWriteOptions, FsWriteResult } from '@napplet/core';

/**
 * Napplet NAP fs shim entrypoint.
 *
 * @module
 */

/**
 * Handle fs.* messages from the shell via the central message listener.
 * Covers request results and runtime-pushed fs.changed events.
 *
 * @param msg  The shell envelope to route
 */
declare function handleFsMessage(msg: {
    type: string;
    [key: string]: unknown;
}): void;
/**
 * Discover visible roots, coarse root permissions, and runtime limits.
 * Advisory discovery only -- never treat it as an authorization token.
 *
 * @returns Promise resolving to the runtime's filesystem discovery data
 *
 * @example
 * ```ts
 * const { roots, limits } = await info();
 * ```
 */
declare function info(): Promise<FsInfo>;
/**
 * Ask the runtime to let the user select one file.
 *
 * @param options  Optional picker hints
 * @returns Promise resolving to picked virtual filesystem paths
 */
declare function pickFile(options?: FsPickOptions): Promise<FsPickResult>;
/**
 * Ask the runtime to let the user select one or more files.
 *
 * @param options  Optional picker hints
 * @returns Promise resolving to picked virtual filesystem paths
 */
declare function pickFiles(options?: FsPickOptions): Promise<FsPickResult>;
/**
 * Ask the runtime to let the user select one directory.
 *
 * @param options  Optional picker hints
 * @returns Promise resolving to picked virtual filesystem paths
 */
declare function pickDirectory(options?: FsPickOptions): Promise<FsPickResult>;
/**
 * Ask the runtime to let the user select or name one file destination.
 *
 * @param options  Optional picker hints
 * @returns Promise resolving to picked virtual filesystem paths
 */
declare function pickSaveFile(options?: FsPickOptions): Promise<FsPickResult>;
/**
 * Read coarse metadata for a visible file or directory.
 *
 * @param path  Virtual absolute path of the entry
 * @returns Promise resolving to the entry metadata
 */
declare function stat(path: string): Promise<FsMetadata>;
/**
 * List the direct children of a visible directory. Ordering is unspecified.
 *
 * @param path  Virtual absolute path of the directory
 * @returns Promise resolving to the directory entries
 */
declare function list(path: string): Promise<FsDirectoryEntry[]>;
/**
 * Read bytes from a visible file.
 *
 * @param path     Virtual absolute path of the file
 * @param options  Optional range read controls
 * @returns Promise resolving to the read result
 */
declare function read(path: string, options?: FsReadOptions): Promise<FsReadResult>;
/**
 * Write bytes to a visible file. `data` is RFC 4648 standard padded base64 text.
 *
 * @param path     Virtual absolute path of the file
 * @param data     Decoded bytes encoded as standard padded base64 text
 * @param options  Optional write mode and preconditions
 * @returns Promise resolving to the write result
 */
declare function write(path: string, data: string, options?: FsWriteOptions): Promise<FsWriteResult>;
/**
 * Create a directory.
 *
 * @param path     Virtual absolute path of the directory to create
 * @param options  Optional recursive parent creation
 * @returns Promise resolving once the runtime acknowledges the creation
 */
declare function mkdir(path: string, options?: FsMkdirOptions): Promise<void>;
/**
 * Remove a file or directory.
 *
 * @param path       Virtual absolute path of the entry to remove
 * @param recursive  Remove a non-empty directory and its authorized descendants
 * @returns Promise resolving once the runtime acknowledges the removal
 */
declare function remove(path: string, recursive?: boolean): Promise<void>;
/**
 * Move or rename a file or directory.
 *
 * @param fromPath  Virtual absolute source path
 * @param toPath    Virtual absolute destination path
 * @returns Promise resolving once the runtime acknowledges the move
 */
declare function move(fromPath: string, toPath: string): Promise<void>;
/**
 * Start an advisory watch on a visible path.
 *
 * @param path     Virtual absolute path to watch
 * @param options  Optional recursive descendant coverage
 * @returns Promise resolving to the runtime-generated watch id
 */
declare function watch(path: string, options?: FsWatchOptions): Promise<string>;
/**
 * Stop a watch. Unknown ids may be treated as successful no-ops by the runtime.
 *
 * @param watchId  Runtime-generated watch id
 * @returns Promise resolving once the runtime acknowledges the request
 */
declare function unwatch(watchId: string): Promise<void>;
/**
 * Register for runtime-pushed filesystem change events.
 *
 * @param handler  Called with each advisory change
 * @returns A Subscription with `close()` to stop listening
 */
declare function onChanged(handler: (change: FsChange) => void): Subscription;
/**
 * Install the fs shim. Registration-only -- requests are issued on demand.
 *
 * @returns cleanup function that clears pending requests and change handlers
 */
declare function installFsShim(): () => void;

export { handleFsMessage, info, installFsShim, list, mkdir, move, onChanged, pickDirectory, pickFile, pickFiles, pickSaveFile, read, remove, stat, unwatch, watch, write };