/**
 * Host-wide file API — browse, download, upload, mkdir.
 *
 * The dashboard is a trusted-operator surface: a paired device
 * already equals terminal access, so there is no project jail. Path handling
 * still canonicalizes and rejects confusion tricks so the *API* cannot be
 * abused: percent-decode checks, null-byte rejection, symlink resolution to a
 * real absolute path, and server-side logging of every operation.
 */
import type { Writable } from "node:stream";
import type { DirListingDto } from "../shared/protocol.js";
export type FileOpLogger = (operation: string, path: string, detail?: string) => void;
/**
 * Canonicalize a client-supplied path. Throws (status 400) on anything
 * suspicious rather than guessing. Returns the resolved absolute path with
 * symlinks in the *parent* chain resolved (the leaf may not exist yet for
 * writes, so its parent is what gets realpath'd).
 */
export declare function canonicalizePath(raw: string, opts: {
    mustExist: boolean;
}): Promise<string>;
/** Resolve and canonicalize an existing directory supplied by a Dashboard client. */
export declare function resolveExistingDirectory(rawPath: string): Promise<string>;
export declare class FileApi {
    private readonly log;
    constructor(log: FileOpLogger);
    /** Resolve an existing directory for listing and context-trust RPC operations. */
    resolveDirectory(rawPath: string): Promise<string>;
    list(rawPath: string): Promise<Omit<DirListingDto, "contextTrust">>;
    /** Resolve a download target; returns the canonical path (must be a file). */
    resolveDownload(rawPath: string): Promise<{
        path: string;
        size: number;
    }>;
    /**
     * Upload into a directory. Refuses to overwrite unless `overwrite` is set —
     * the collision surfaces as 409 so the client can prompt.
     */
    prepareUpload(rawDir: string, fileName: string, overwrite: boolean): Promise<{
        path: string;
        stream: Writable;
        commit: () => Promise<void>;
        cleanup: () => Promise<void>;
    }>;
    mkdir(rawDir: string, name: string): Promise<string>;
}
/** Places shown as shortcuts in the files tab. */
export declare function defaultPlaces(homeDir: string, projectRoots: string[]): Array<{
    label: string;
    path: string;
}>;
//# sourceMappingURL=files.d.ts.map